Hata Kodları

Tüm hatalar standart zarf içinde error.code (İngilizce slug) ve error.message (insan-okunur, Türkçe) ile döner. Kod (slug) programatik kontrol için stabildir; mesaj metni değişebilir.

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Girdi doğrulaması başarısız.",
    "details": { "field": "period" }
  },
  "meta": { "trace_id": "...", "timestamp": "..." }
}

Genel HTTP Hataları

HTTP	code	Anlamı
400	invalid_input	Geçersiz veya eksik girdi
400	missing_idempotency_key	Zorunlu Idempotency-Key başlığı yok
401	unauthorized	Kimlik doğrulama başarısız (eksik/hatalı key veya secret)
403	forbidden	Erişim yetkisi yok (örn. servis sahibi değilsiniz)
404	not_found	Kaynak bulunamadı
405	method_not_allowed	HTTP metodu bu uç noktada desteklenmiyor
409	conflict	Çakışan istek (örn. downgrade denemesi)
422	validation_error	İş kuralı doğrulaması başarısız
429	rate_limited	İstek limiti aşıldı (bkz. Rate Limit)
500	internal_error	Sunucu tarafı beklenmeyen hata

Alan (Domain) Hataları

HTTP	code	Anlamı
402/422	insufficient_credit	Kredi bakiyesi işlem için yetersiz
422	idempotency_key_reuse	Aynı Idempotency-Key farklı gövde ile kullanıldı
422	location_locked	Yükseltme sırasında lokasyon değiştirilemez
404	webhook_not_found	Webhook endpoint kaydı bulunamadı
409	webhook_limit_exceeded	Bayi başına maksimum aktif webhook sayısı aşıldı

Nasıl Ele Almalı?

• Programatik kontrolde daima error.code'a bakın, mesaj metnine değil.
• 5xx ve 429 hatalarında tekrar deneme (retry) mantıklıdır; 4xx hatalarında (429 hariç) istek düzeltilmeden tekrar denemeyin.
• Destek talebinde meta.trace_id değerini paylaşın — sunucu loglarında ilgili isteği bulmayı sağlar.