Hatalar, tekrarlı istekler ve yeniden deneme

Fraud uçları platformun tek hata zarfını kullanır. Bu sayfa yalnız fraud'a özgü kodları, kota yanıtını ve yeniden deneme kurallarını toplar.

🚫

message değil code üzerinden dallanın. message insan içindir, çevrilir ve zamanla değişir. code sözleşmenin parçasıdır.

Hata zarfı

{
  "status": "failure",
  "code": "FRAUD_CHANNEL_NOT_DECLARABLE",
  "message": "…",
  "statusCode": 400,
  "timestamp": "2026-10-05T09:12:44.816Z",
  "service": "api-gateway",
  "systemTime": 1791277964816,
  "requestId": "req_7f3d9c1a4b2e"
}

requestId her yanıtta X-Request-Id başlığında da döner. Bir destek talebinde verdiğiniz değer budur.

Başarılı yanıtta `status`

⚠️

Başarı zarfında success alanı yoktur. Fraud uçlarının başarılı yanıtı üst seviyede status: "success" taşır; yük data altındadır. İstemcide response.success okuyan bir kontrol her zaman undefined görür — status alanını ya da HTTP durum kodunu okuyun.

Karar API'si — doğrulama hataları (400)

`code`	Neden
`VALIDATION_ERROR`	Bir alan tipi ya da uzunluğu geçersiz, ya da belgelenmemiş bir üst seviye alan gönderildi. Alan kırılımı `details.errors` içinde döner
`FRAUD_CHANNEL_NOT_DECLARABLE`	Yalnız Lunixi'nin kendi servislerine ait bir kanal ya da ürün bağlamı beyan edildi (ör. `productContext: hosted_payment_form`)
`FRAUD_SUB_MERCHANT_REF_MISMATCH`	`subMerchantRef` ile `merchant.merchantRef` farklı. İkisi aynı kavramdır; hangi alt işyerinin değerlendirildiği belirsiz kalamaz
`FRAUD_SUB_MERCHANT_REF_INVALID`	Alt işyeri referansı biçime uymuyor (harf, rakam ve `. _ : @ -`; en fazla 180 karakter)
`FRAUD_ASSERTION_CHANNEL_INVALID`	`identityAssertion` yalnız `channel: merchant_form` ile gönderilebilir
`FRAUD_ASSERTION_SUBJECT_REQUIRED`	`identityAssertion` gönderildi ama `subjectId` yok. Bağlanacak bir konu olmadan artefakt doğrulanamaz

channel ve integrationMode kapalı sözlüklerdir. Dışarıdan beyan edilebilen kanallar merchant_form ve standalone_api; integrationMode yalnız standalone olabilir. lunixi_checkout ve wallet kanalları Lunixi'nin kendi servislerinden gelir, çünkü o kanallara bağlı akışların dışarıdan tetiklenmesi doğru olmazdı.

Olay alımı — doğrulama hataları (400)

`code`	Neden
`FRAUD_EVENT_INVALID`	Zorunlu alan eksik, `eventType` sözlük dışı, sözlüklü bir alan tanınmayan değer taşıyor, ya da olay türünün gerektirdiği alan yok
`FRAUD_EVENT_BATCH_INVALID`	Parti gövdesi ne bir dizi ne de `{ "events": [...] }`
`FRAUD_EVENT_BATCH_TOO_LARGE`	Parti 500 olaydan fazla. Partinin tamamı reddedilir

Parti çağrısında tek tek olayların doğrulaması results[].error alanında döner ve HTTP durumu 200 kalır — failed alanını her zaman kontrol edin. Beklenmeyen bir iç hata o olayda FRAUD_EVENT_INGEST_FAILED olarak görünür; ayrıntı yanıta çıkmaz.

Kimlik doğrulama (401 / 403)

`code`	Durum	Neden
`AUTH_HEADERS_MISSING`	401	`X-Key-Id`, `X-Date`, `X-Nonce` ya da `X-Signature` yok
`INVALID_DATE`	401	`X-Date` beş dakikalık pencerenin dışında
`NONCE_REPLAY`	401	Aynı anahtar + aynı nonce ikinci kez kullanıldı
`INVALID_KID`	401	`X-Key-Id` tanınmıyor
`DIGEST_MISSING`	401	Gövdesi olan istekte `Digest` başlığı yok
`INVALID_DIGEST`	401	Özet gövdeyle uyuşmuyor — neredeyse her zaman girintili JSON imzalanmasından kaynaklanır
`INVALID_SIGNATURE`	401	Kanonik dizgenin imzası doğrulanamadı
`MERCHANT_SUSPENDED`	403	Hesap etkin değil
`IP_NOT_ALLOWED`	403	İstek, anahtara tanımlı IP listesi dışından geldi

Yetki ve ürün kapısı (403 / 503)

`code`	Durum	Neden
`PRODUCT_NOT_ENABLED`	403	Kimlik `FRAUD_SERVICE` ürününe yetkili değil
`PRODUCT_ENTITLEMENT_UNAVAILABLE`	503	Ürün yetkisi doğrulanamadı. Geçicidir; `Retry-After` varsa ona uyun
`PRODUCT_ENTITLEMENT_NOT_RESOLVED`	403	Token ürün damgası olmadan basılmış
`fraud.module.not_enabled`	403	`subMerchantRef` gönderildi ama hesapta alt işyeri / ödeme kuruluşu modülü açık değil. `details.module` hangi modül olduğunu söyler
`FRAUD_PANEL_SURFACE_NOT_MACHINE_CALLABLE`	403	İstenen uç fraud operasyon konsoluna aittir ve API anahtarıyla çağrılamaz

⚠️

Panel yüzeyi ile API yüzeyi ayrıdır. API anahtarıyla çağrılabilen fraud uçları yalnız bu dokümantasyonda belgelenenlerdir: karar, olay alımı ve karar kayıtları. Operasyon konsolunun uçları panel oturumuyla çalışır ve varsayılan olarak makine çağıranına kapalıdır.

Sayfalama (400)

`code`	Neden
`INVALID_CURSOR`	`cursor` değeri bozuk. Sessizce ilk sayfaya dönülmez: bir mutabakat döngüsünde aynı sayfanın iki kez işlenmesi demek olurdu

Kota (429 / 503)

`code`	Durum	Neden
`fraud.quota.exceeded`	429	Günlük kota doldu ya da istek hızı limiti aşıldı. `details.breach` hangisi olduğunu söyler
`fraud.quota.unavailable`	503	Kota arka ucuna erişilemedi. Yalnız olay alımında döner

Karar yolu kota arka ucu erişilemezse durmaz. Kota kontrolü atlanır ve karar üretilmeye devam eder; ödeme bir sayaç yüzünden durmamalıdır. Olay alımında ise 503 döner: olayı yeniden gönderebilirsiniz, böylece ne olay kaybolur ne de kota delinir.

Kota başlıkları

Kota reddinde yanıt şu başlıkları taşır. Değerler uydurulmaz: hepsi kotayı uygulayan katmanın döndürdüğü gerçek sayılardır, dolayısıyla bir değer bilinmiyorsa o başlık hiç basılmaz.

Başlık	Anlamı
`Retry-After`	Kaç saniye sonra yeniden denenebilir
`X-RateLimit-Limit`	Hız limiti
`X-RateLimit-Remaining`	Pencerede kalan istek
`X-RateLimit-Reset`	Günlük sayacın sıfırlanma anı (epoch saniye)
`X-Quota-Limit`	Günlük kota
`X-Quota-Remaining`	Günlük kotadan kalan
`X-Quota-Reset`	Günlük kotanın sıfırlanma anı (epoch saniye)

Aynı değerler yanıt gövdesinin details.quota alanında da döner. Başlıkların yokluğunu bir limit tahminine çevirmeyin — yanlış hızda yeniden denemeye yol açar.

Kota eşiğine yaklaştığınızda fraud.quota.threshold_reached platform webhook olayı gönderilir. Teslimat ve imza: Webhook kurulumu.

Tekrarlı istekler

⚠️

Fraud uçlarında Idempotency-Key başlığı bir tekrar bastırma mekanizması değildir. Tekrar bastırma uca göre farklı çalışır:

Uç	Tekrar davranışı
`POST /fraud/events/transactions`	`eventId` üzerinden bastırılır. Aynı hesap + aynı `eventId` ikinci kez yazılmaz; yanıt `deduplicated: true` döner. Yeniden deneme güvenlidir
`POST /fraud/events/transactions/batch`	Her olay kendi `eventId` değeriyle tek tek bastırılır. Partiyi bütün olarak yeniden gönderebilirsiniz
`POST /fraud/decisions/evaluate`	Bastırma yoktur. İkinci çağrı ikinci bir karar ve ikinci bir karar kaydı üretir. Faturalamada aynı `transactionRef` 30 gün boyunca tek işlem sayılır, ancak bu bir tekrar bastırma değildir — karar yeniden hesaplanır
`GET` uçları	Doğası gereği tekrarlanabilir

Yeniden deneme kuralları

Durum	Yeniden denenir mi
`400` (doğrulama)	Hayır. İsteği düzeltin; aynı istek her zaman aynı yanıtı verir
`401` imza / nonce / tarih	Yalnız yeni bir nonce ve yeni bir `X-Date` ile. Aynı imzayı tekrar göndermek `NONCE_REPLAY` verir
`403` ürün / modül kapısı	Hayır. Yetkilendirme gerekir
`429`	Evet, `Retry-After` kadar bekledikten sonra
`503`	Evet, `Retry-After` kadar bekledikten sonra
`5xx` (diğer)	Olay alımında evet, aynı `eventId` ile. Karar çağrısında otomatik yeniden denemeyin: ödeme anındaki kararın zamanlaması çağıranın elindedir

🚫

Karar çağrısını kör döngüyle yeniden denemeyin. Kart hamili bir yanıt bekliyor; sonsuz deneme hem gecikmeyi büyütür hem de kotanızı tüketir. Karar alınamadığında kendi iş kuralınızı uygulayın (ödemeyi durdurun, elle incelemeye alın ya da kendi yedek eşiğinizle devam edin) ve bu durumu kendi tarafınızda ölçün.

Sonraki adım

Karar Kayıtları Akışlar ve Çözümleme