İçeriğe geç

Hata modeli

RFC 9457 hata gövdesi, hata kodları ve hangisinin yeniden denenebileceği.

Geliştirici belgesi

Her hata yanıtı application/problem+json içerik türüyle RFC 9457 biçimindedir. İstemciniz title, detail ya da message metnine değil, code alanına göre dallanmalıdır: metinler değişebilir, kodlar değişmez. Metinler Türkçedir.

{
  "type": "urn:biik:api:v1:problem:validation_failed",
  "title": "Girdi doğrulanamadı",
  "status": 400,
  "code": "validation_failed",
  "request_id": "5b0d3c9e-2f4a-4e61-9a7b-8c1d2e3f4a5b",
  "errors": [
    { "field": "body.nickname", "code": "unrecognized_keys", "message": "Tanınmayan alan" }
  ]
}

Alanlar

  • type: hata türünün kararlı URN'i, urn:biik:api:v1:problem:<code>.
  • title: insan için kısa başlık.
  • status: HTTP durum kodu.
  • code: makine için hata kodu.
  • request_id: isteğin kimliği. Destek talebinde bu değeri verin.
  • detail: varsa insan için ayrıntı.
  • errors: yalnız validation_failed yanıtında, alan düzeyi hatalar (field, code, message).

Hata kodları

codeHTTPAçıklama
bad_request400Geçersiz istek
validation_failed400Girdi doğrulanamadı
key_in_query400Anahtar sorgu dizesinde gönderilemez
cookie_with_key400Anahtar çerezle birlikte gönderilemez
idempotency_key_required400Idempotency-Key başlığı gerekli
idempotency_key_invalid400Idempotency-Key başlığı geçersiz
cursor_invalid400İmleç geçersiz ya da bu sorguya ait değil
unauthorized401Kimlik doğrulanamadı
insufficient_scope403Anahtarın kapsamı bu işleme yetmiyor
forbidden403Anahtarın rolü bu işleme izin vermiyor
module_disabled403Modül bu hesapta kapalı
trial_ended403Deneme süresi bitti, hesap salt okunur
key_suspended403Anahtar askıda: rolü ya da bağlaması geçersiz
not_found404Kayıt bulunamadı
method_not_allowed405Yöntem desteklenmiyor
idempotency_in_progress409Aynı Idempotency-Key ile süren bir istek var
conflict409İstek kaydın bugünkü durumuyla çakışıyor
payload_too_large413Gövde çok büyük
unsupported_media_type415İçerik türü desteklenmiyor
idempotency_key_reused422Idempotency-Key başka bir istekle kullanılmış
rate_limited429İstek sınırı aşıldı
internal_error500Beklenmeyen hata
timeout503İstek süre sınırını aştı

Yeni bir hata kodu eklenebilir; var olan bir kodun durumu ve anlamı değişmez. Tanımadığınız bir kodu HTTP durumuna göre ele alın.

Ne zaman yeniden denenir

  • 429 rate_limited: Retry-After başlığındaki saniye kadar bekleyip yineleyin (Hız sınırı).
  • 503 timeout: istek süre sınırını aştı ve geri alındı. Retry-After kadar bekleyip yineleyin; liste isteğinde süzgeci daraltmak ya da sayfa boyutunu küçültmek yardımcı olur.
  • 409 conflict: eşzamanlı bir yazımla çakıştı. Retry-After başlığı varsa bekleyip yineleyin; yoksa kaydın güncel hâlini okuyun (örneğin iş e-postası başka bir etkin çalışanda kullanılıyor).
  • 409 idempotency_in_progress: aynı Idempotency-Key ile gönderilen istek hâlâ sürüyor. Biraz bekleyip aynı anahtarla yineleyin.
  • 500 internal_error: POST isteğini aynı Idempotency-Key ile yinelemek güvenlidir.
  • 4xx hataların geri kalanı isteğin kendisindedir; aynı isteği değiştirmeden yinelemek aynı yanıtı verir.