Hatalı istekler uygun bir HTTP durum kodu ve makine tarafından okunabilir bir hata kodu ile döner. Hata mesajları kullanıcıya gösterilecek şekilde değil, geliştiriciyi yönlendirecek şekilde yazılmıştır.
Hata yanıtı yapısı
Tüm hatalar aynı zarfı kullanır: success alanı false olur ve error nesnesi kod, mesaj ve varsa ayrıntıları taşır.
{
"success": false,
"error": {
"code": "insufficient_credits",
"message": "Kredi bakiyeniz bu istek için yeterli değil.",
"details": { "required": 20, "balance": 4 }
}
}Durum kodları
| HTTP | Hata kodu | Anlamı |
|---|---|---|
| 400 | bad_request |
İstek gövdesi okunamadı veya beklenen JSON yapısında değil. |
| 401 | unauthenticated |
Authorization başlığı yok, anahtar geçersiz veya iptal edilmiş. |
| 402 | insufficient_credits |
Kredi bakiyesi veya aylık kota bu istek için yeterli değil. |
| 403 | plan_forbidden |
Bu endpoint mevcut planınızın kapsamı dışında. |
| 404 | not_found |
İstenen endpoint veya kaynak bulunamadı. |
| 422 | validation_failed |
Parametreler doğrulamadan geçmedi; ayrıntılar details alanında alan bazında listelenir. |
| 429 | rate_limited |
Dakikalık hız limiti aşıldı. Retry-After başlığı kadar bekleyin. |
| 500 | server_error |
Beklenmeyen bir sunucu hatası. Kredi düşülmez, isteği tekrar deneyebilirsiniz. |
Tekrar deneme stratejisi
429 ve 5xx yanıtlarında üstel geri çekilme (exponential backoff) ile en fazla üç kez tekrar deneyin. 4xx yanıtlarını (429 hariç) tekrar denemeyin; istek düzeltilmeden aynı sonucu verir.