Hata kodları
Tutarlı hata zarfı + retry semantiği
Her error response aynı şemayı izler. Geçici (5xx, 429) hataları retry edin, kalıcı (4xx) hatalarda payload'u düzeltin.
Zarf
Tutarlı error envelope
Tüm hata yanıtları aynı şemayı izler. error.code stabil ve programatik karar verme içindir; message insan okunabilir. requestId değerini destek talebinizde paylaşın — biz log'da bulabilelim.
error envelope
{
"error": {
"code": "VALIDATION_FAILED",
"message": "lines: at least one line is required",
"details": [
{ "path": "lines", "constraint": "arrayNotEmpty" }
],
"requestId": "req_01J9XZ7K3F2N…"
}
}HTTP statusler
Hangi durum ne anlama gelir?
| Status | Code | Anlamı | Retry |
|---|---|---|---|
| 400 | BAD_REQUEST | Malformed JSON, eksik content-type. | Retry etme |
| 401 | UNAUTHORIZED | X-Integration-Key yok, geçersiz veya iptal. | Retry etme |
| 403 | FORBIDDEN | Anahtar geçerli ama bu endpoint'e yetki yok. | Retry etme |
| 404 | NOT_FOUND | GET endpoint'i için ID hiç yok. | Retry etme |
| 409 | IDEMPOTENCY_CONFLICT | Aynı Idempotency-Key farklı payload ile tekrar geldi. | Retry etme |
| 422 | VALIDATION_FAILED | Payload şema veya iş kuralı ihlali. | Retry etme |
| 429 | RATE_LIMITED | Saniye/dakika başına limit aşıldı. | Backoff ile |
| 500 | INTERNAL_ERROR | Beklenmedik server hatası. | Retry et |
| 503 | SERVICE_UNAVAILABLE | Geçici kapasite veya dependency hatası. | Retry et |
Validation hatası
422 — payload şema ihlali
response
HTTP/1.1 422 Unprocessable Entity
{
"error": {
"code": "VALIDATION_FAILED",
"message": "Validation failed",
"details": [
{ "path": "lines.0.unitAmountMinor", "constraint": "isInt" },
{ "path": "occurredAt", "constraint": "isIso8601" }
],
"requestId": "req_01J9XZ…"
}
}Idempotency çakışması
409 — aynı key, farklı payload
response
HTTP/1.1 409 Conflict
{
"error": {
"code": "IDEMPOTENCY_CONFLICT",
"message": "Idempotency-Key already used with a different payload hash",
"requestId": "req_01J9XZ…"
}
}Retry stratejisi
Doğru durumda doğru retry
Geçici hatalar — exponential backoff
429, 500, 503 alırsanız her seferinde Idempotency-Key'i AYNI tutarak yeniden deneyin. Önerilen: 1s → 2s → 4s → 8s → 16s, maksimum 5 deneme.
Kalıcı hatalar — payload düzelt
400, 401, 403, 409, 422 ise istek tekrarlanırsa aynı şekilde başarısız olur. Mesajdaki details listesindeki path/constraint'leri kullanarak payload'u düzeltin.