İçeriğe geç

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ı

results[].status değerleri
DurumAnlamıYapmanız gereken
APPLIEDKarar uygulandı (kanıt ve geçmiş yazıldı; ETK ise İYS sırasına alındı).Başarı sayın.
DUPLICATEAynı durum zaten kayıtlı ve bu karar daha yeni değil; değişiklik yok.Başarı sayın, tekrar göndermeyin.
REJECTEDKarar 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.

results[].code değerleri
KodAnlamıYapmanız gereken
AMBIGUOUS_CONTACTTelefon/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_CONTACTTelefon geçersiz (ve e-posta yok) ya da kimlik üretilemedi.Veriyi düzeltip yeni externalEventId ile gönderin.
INVALID_DECIDED_ATdecidedAt ayrıştırılamadı (geçersiz ay/gün, aşırı offset vb.).Değeri düzeltin.
DECIDED_AT_IN_FUTUREdecidedAt şu andan 5 dakikadan fazla ileride.Sunucu saatinizi (NTP) düzeltin.
DECISION_TOO_OLDKVKK 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_REQUIREDETK ONAY kararı 3 iş gününden eski; reapprovalRequired: true gelir.Kişiden yeniden onay alın ve yeni karar gönderin.
CHANNEL_NOT_AVAILABLEETK 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_TYPEconsentTypeSlug bilinmiyor (veya ETK/KVKK_ETK).Geçerli bir KVKK izin türü kodu kullanın.
STALE_DECISIONAynı 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 durum kodları
HTTPNe zamandata.codeYapmanız gereken
200İşlendi. Karar bazlı sonuç results içinde, toplu istekte olay hatası events[].error içindedir.—results alanını kontrol edin.
400Geç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.yokDüzeltmeden tekrar etmeyin.
401Kimlik doğrulama başarısız (neden bilerek belirsiz).yokAnahtar, secret, saat, ham gövde ve bağlantı durumunu kontrol edin.
402Şirketinizin paketinde API Erişimi modülü yok.MODULE_NOT_IN_PLANPaketinize API Erişimi modülünü ekleyin; aynı isteği tekrar denemek işe yaramaz.
409Aynı idempotency anahtarı farklı gövdeyle (veya aynı olay kimliği başka anahtarla) gönderildi.IDEMPOTENCY_CONFLICTYeni externalEventId kullanın; gerçek tekrar ise birebir aynı gövdeyi gönderin.
413Gövde 256 KB sınırını aşıyor (pratikte yaklaşık 100 KB üzerinde de dönebilir).yokToplu isteği yaklaşık 50 olay / en çok 100 KB olacak şekilde bölün.
422Müşteri kimliği bağlantıyla eşleşmiyor; sorguda çoklu eşleşme.CUSTOMER_MISMATCH veya AMBIGUOUS_CONTACTAnahtar–müşteri eşleşmesini kontrol edin. Aynı isteği tekrar denemek işe yaramaz.
429İstek sınırı aşıldı.yokRetry-After kadar bekleyip üstel geri çekilmeyle, aynı Idempotency-Key ile tekrar deneyin.
503Kanıt altyapısı geçici olarak hazır değil; kanıtsız kabul yapılmaz.yokGeri çekilerek tekrar deneyin; süreklilik gösterirse Rıza AL ekibine bildirin.
5xx (diğer)Sunucu hatası.yokAynı 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-Key başlığıdır; yoksa externalEventId kullanı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: true ve ilk işlemin saklı sonucu döner. Ağ zaman aşımından sonra körlemesine tekrar deneyebilirsiniz.
  • Aynı anahtar + farklı gövde 409 IDEMPOTENCY_CONFLICT döner.
  • Farklı Idempotency-Key ile aynı externalEventId gönderirseniz, ilk işlem makbuz yazdıysa yine 409 IDEMPOTENCY_CONFLICT alırsınız.
  • Toplu istekte Idempotency-Key verirseniz her olayın anahtarı <key>:<externalEventId> olur; vermezseniz externalEventId kullanılır.
  • Her olay tek işlemde (transaction) işlenir; yarım uygulanmış olay kalmaz.

İstek sınırları

İstek ve boyut sınırları
SınırDeğer
Bağlantı başına dakikalık bütçeVarsayı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şınaDakikada 1200 istek (kimlik doğrulamasından önce uygulanan kaba sınır).
Tek olayEn çok 50 karar.
Toplu istekEn çok 100 olay; güvenli boyut için yaklaşık 50 olay ve 100 KB altı önerilir.
Durum sorgusuEn ç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).