NoktanyusYunus Tuğhan

Error contract

API hata kodları

Her hata için sabit error.code, HTTP durumu, retry uygunluğu ve ne yapman gerektiği. Agent / SDK entegrasyonlarında mesaj metnine değil koda güven.

OpenAPI Docs Başlangıç Sistem durumu

Ortak zarf

{ "success": false, "error": { "code": "…", "message": "…" } }

HTTP 400VALIDATIONFix request
Doğrulama hatası
İstek gövdesini OpenAPI şemasına göre düzelt; fieldErrors alanlarını oku.
```
{"success":false,"error":{"code":"VALIDATION","message":{"fieldErrors":{"iban":["Zorunlu"]}}}}
```
HTTP 401UNAUTHORIZEDFix request
Anahtar yok / geçersiz
Authorization: Bearer nok_live_… veya x-api-key başlığını ekle; Dashboard → API Keys.
```
{"success":false,"error":{"code":"UNAUTHORIZED","message":"API key required…"}}
```
HTTP 401INVALID_KEYFix request
Anahtar reddedildi
Anahtarın iptal/süresi dolmuş olabilir; yeni anahtar oluştur.
```
{"success":false,"error":{"code":"INVALID_KEY","message":"Invalid API key"}}
```
HTTP 402QUOTA_EXCEEDEDFix request
Kota veya kredi bitti
Plan yükselt veya /magaza/krediler üzerinden kredi yükle; sonra isteği tekrarla.
```
{"success":false,"error":{"code":"QUOTA_EXCEEDED","message":"Aylık istek kotanız dolmuştur…"}}
```
HTTP 429RATE_LIMITEDRetryable
Hız sınırı
Retry-After (sn) kadar bekle; exponential backoff uygula. X-RateLimit-* başlıklarını izle.
```
{"success":false,"error":{"code":"RATE_LIMITED","message":"Too many requests"}}
```
HTTP 500INTERNAL_ERRORRetryable
Sunucu hatası
Kısa backoff ile 1–2 kez dene; sürerse /durum ve destek kanalını kontrol et.
```
{"success":false,"error":{"code":"INTERNAL_ERROR","message":"Unexpected error"}}
```