Hata kodları, idempotency ve istek sınırları
Karar sonuçları, REJECTED kodları, HTTP durum kodları, tekrar gönderim güvenliği ve dakikalık istek sınırı.
Son güncelleme:
Karar sonuçları
| Durum | Anlamı | Yapmanız gereken |
|---|---|---|
APPLIED | Karar uygulandı (kanıt ve geçmiş yazıldı; ETK ise İYS sırasına alındı). | Başarı sayın. |
DUPLICATE | Aynı durum zaten kayıtlı ve bu karar daha yeni değil; değişiklik yok. | Başarı sayın, tekrar göndermeyin. |
REJECTED | Karar işlenmedi; nedeni code alanındadır. | Aşağıdaki tabloya göre hareket edin. |
REJECTED kodları
REJECTED sonuçlar HTTP 200 ile döner. Olayın tüm kararları reddedilirse kişi oluşturulmaz.
| Kod | Anlamı | Yapmanız gereken |
|---|---|---|
AMBIGUOUS_CONTACT | Telefon/e-posta şirkette birden çok kişiyle eşleşti; tahmin yapılmaz. | Otomatik tekrar etmeyin; kişi mükerrerlerinin çözülmesi için Rıza AL ekibiyle iletişime geçin. |
INVALID_CONTACT | Telefon geçersiz (ve e-posta yok) ya da kimlik üretilemedi. | Veriyi düzeltip yeni externalEventId ile gönderin. |
INVALID_DECIDED_AT | decidedAt ayrıştırılamadı (geçersiz ay/gün, aşırı offset vb.). | Değeri düzeltin. |
DECIDED_AT_IN_FUTURE | decidedAt şu andan 5 dakikadan fazla ileride. | Sunucu saatinizi (NTP) düzeltin. |
DECISION_TOO_OLD | KVKK veya ETK-RET kararı izin verilen azami yaştan (şu an 30 gün) eski. | Yeniden göndermeyin; gerekiyorsa yeni onay alın. |
CONSENT_TOO_OLD_REAPPROVAL_REQUIRED | ETK ONAY kararı 3 iş gününden eski; reapprovalRequired: true gelir. | Kişiden yeniden onay alın ve yeni karar gönderin. |
CHANNEL_NOT_AVAILABLE | ETK kanalı (SMS/e-posta) şirketinizin izin kataloğunda aktif değil. ARAMA bu kodu almaz. | İzin kataloğunu Rıza AL ekibiyle kontrol edin. |
UNKNOWN_CONSENT_TYPE | consentTypeSlug bilinmiyor (veya ETK/KVKK_ETK). | Geçerli bir KVKK izin türü kodu kullanın. |
STALE_DECISION | Aynı kişi ve kanal için daha yeni bir karar zaten kayıtlı; bu ONAY eski. | Yok sayın; bu doğru davranıştır. |
HTTP durum kodları
| HTTP | Ne zaman | data.code | Yapmanız gereken |
|---|---|---|---|
| 200 | İşlendi. Karar bazlı sonuç results içinde, toplu istekte olay hatası events[].error içindedir. | — | results alanını kontrol edin. |
| 400 | Geçersiz gövde: method eksik/geçersiz, decidedAt offset'siz, ETK'da channel yok, phone/email yok, 50'den fazla karar veya 100'den fazla olay. message alan alan hata listesidir. | yok | Düzeltmeden tekrar etmeyin. |
| 401 | Kimlik doğrulama başarısız (neden bilerek belirsiz). | yok | Anahtar, secret, saat, ham gövde ve bağlantı durumunu kontrol edin. |
| 402 | Şirketinizin paketinde API Erişimi modülü yok. | MODULE_NOT_IN_PLAN | Paketinize API Erişimi modülünü ekleyin; aynı isteği tekrar denemek işe yaramaz. |
| 409 | Aynı idempotency anahtarı farklı gövdeyle (veya aynı olay kimliği başka anahtarla) gönderildi. | IDEMPOTENCY_CONFLICT | Yeni externalEventId kullanın; gerçek tekrar ise birebir aynı gövdeyi gönderin. |
| 413 | Gövde 256 KB sınırını aşıyor (pratikte yaklaşık 100 KB üzerinde de dönebilir). | yok | Toplu isteği yaklaşık 50 olay / en çok 100 KB olacak şekilde bölün. |
| 422 | Müşteri kimliği bağlantıyla eşleşmiyor; sorguda çoklu eşleşme. | CUSTOMER_MISMATCH veya AMBIGUOUS_CONTACT | Anahtar–müşteri eşleşmesini kontrol edin. Aynı isteği tekrar denemek işe yaramaz. |
| 429 | İstek sınırı aşıldı. | yok | Retry-After kadar bekleyip üstel geri çekilmeyle, aynı Idempotency-Key ile tekrar deneyin. |
| 503 | Kanıt altyapısı geçici olarak hazır değil; kanıtsız kabul yapılmaz. | yok | Geri çekilerek tekrar deneyin; süreklilik gösterirse Rıza AL ekibine bildirin. |
| 5xx (diğer) | Sunucu hatası. | yok | Aynı Idempotency-Key ile tekrar deneyin. |
data.code yalnızca MODULE_NOT_IN_PLAN, CUSTOMER_MISMATCH, AMBIGUOUS_CONTACT ve IDEMPOTENCY_CONFLICT hatalarında bulunur. 400, 401, 413, 429 ve 503 yanıtlarında data null'dır ve message okunur Türkçe bir metindir (400'de dizi olabilir).
Idempotency ve tekrar gönderim
- Anahtar,
Idempotency-Keybaşlığıdır; yoksaexternalEventIdkullanılır. 191 karakterden uzun anahtarlar reddedilmez, kısaltılarak işlenir. - Aynı anahtar + aynı gövde güvenle yeniden gönderilebilir: yanıtta
duplicate: trueve ilk işlemin saklı sonucu döner. Ağ zaman aşımından sonra körlemesine tekrar deneyebilirsiniz. - Aynı anahtar + farklı gövde
409 IDEMPOTENCY_CONFLICTdöner. - Farklı
Idempotency-Keyile aynıexternalEventIdgönderirseniz, ilk işlem makbuz yazdıysa yine409 IDEMPOTENCY_CONFLICTalırsınız. - Toplu istekte
Idempotency-Keyverirseniz her olayın anahtarı<key>:<externalEventId>olur; vermezsenizexternalEventIdkullanılır. - Her olay tek işlemde (transaction) işlenir; yarım uygulanmış olay kalmaz.
İstek sınırları
| Sınır | Değer |
|---|---|
| Bağlantı başına dakikalık bütçe | Varsayılan olarak dakikada 6000 birim. Tekil olay veya sorgu 1, toplu istek olay sayısı kadar, durum sorgusu kişi sayısı kadar birim tüketir; hepsi aynı bütçeyi paylaşır. Yüksek hacim ihtiyacınız varsa Rıza AL ekibiyle görüşün. |
| IP başına | Dakikada 1200 istek (kimlik doğrulamasından önce uygulanan kaba sınır). |
| Tek olay | En çok 50 karar. |
| Toplu istek | En çok 100 olay; güvenli boyut için yaklaşık 50 olay ve 100 KB altı önerilir. |
| Durum sorgusu | En çok 500 kişi. |
| Sorgu yanıtı | En çok 200 karar. |
Sınır aşıldığında 429 ve Retry-After başlığı (saniye) döner. Üstel geri çekilme uygulayın ve toplu işleri zamana yayın.
Güvenlik notları
- Her kimlik hatası aynı yanıtı döner; hata mesajından bilgi sızdırılmaz.
- Şirket kapsamı yalnızca bağlantıdan gelir; tüm kişi sorguları şirkete özeldir.
- Webhook payload'ında, sorgu yanıtlarında ve makbuzlarda telefon, e-posta veya ad bulunmaz.
- Kanıt altyapısı hazır değilse istekler kabul edilmez (
503); kanıtsız kayıt tutulmaz. - API anahtarınızı ve secret'ınızı yalnızca sunucu tarafında, gizli yönetim aracınızda saklayın.
API anahtarınızı ve bağlantınızı yönetmek için panelde Hesabım → Şirket Ayarları → API Erişimi sekmesini kullanın. Hesabım sayfasını aç (giriş yapmanız gerekir).
