Başlangıç

Hata Kodları

Hata zarfı, HTTP durumları ve kod tablosu, kısmi başarı, geçici ve kalıcı hatalar.

Son güncelleme: 21 Eylül 2026 · Sözleşme sürümü 1.0.0

Her hata aynı zarfla döner. request_id değerini destek taleplerinde iletin; details[] alan bazında sorunu açıklar ve toplu uçlarda satır index değerini taşır.

{
  "error": {
    "code": "validation_error",
    "message": "3 kayıt doğrulanamadı.",
    "details": [
      { "index": 4,  "field": "tax_number", "issue": "VKN 10 haneli olmalı" },
      { "index": 17, "field": "amount",     "issue": "Tutar boş olamaz" }
    ]
  },
  "request_id": "req_035866d61b6e4e958c00b40298d874ee"
}

Kod tablosu

HTTP	code	Ne zaman
400	`validation_error`	Gövde ya da parametre hatalı; `details[]` alan bazında açıklar
401	`unauthenticated`	Anahtar yok, geçersiz, iptal edilmiş ya da süresi dolmuş
402	`quota_exceeded`	Paket kotası doldu (satır ya da aylık mutabakat)
403	`plan_required · key_suspended · ip_not_allowed · insufficient_scope`	Paket API'ye açık değil · anahtar askıda · IP izin listesi dışı · kapsam yetersiz
404	`not_found`	Kayıt yok ya da başka firmaya ait (ayrım yapılmaz)
409	`idempotency_conflict · idempotency_in_progress · state_conflict · results_not_ready · snapshot_too_old · request_not_active · request_already_claimed`	Aynı Idempotency-Key farklı gövde · aynı istek hâlâ çalışıyor · durum bu işlemi kabul etmiyor · sonuç henüz yok · eski sonuç biçimi · talep açık değil · talebi başka anahtar aldı
410	`export_consumed · file_expired`	Tek indirmelik dışa aktarma alınmış · `file_id` 24 saati geçmiş
413	`payload_too_large`	Satır sayısı, gövde ya da dosya sınırı aşıldı
422	`unprocessable · request_kind_mismatch · request_params_mismatch · origin_not_api`	Biçim doğru ama iş kuralı engelliyor · teslimat gövdesi talebin türüne uymuyor · parametre uyuşmazlığı · iş panelden açılmış
429	`rate_limited · email_budget_exceeded`	Hız sınırı (`Retry-After`) · günlük e-posta bütçesi
500	`internal_error`	Sunucu hatası; `request_id` ile destek talebi açın
503	`integration_disabled · maintenance`	API geçici olarak kapalı ya da bakımda

Kısmi başarı

Cari listesi teslimatı (complete { counterparties }) hata yerine 200 ve delivery { accepted, rejected, errors[] } döner: kabul edilenler yazılır, reddedilenler index ile listelenir. Yalnız reddedilenleri düzeltip bir sonraki talepte yeniden gönderin. Ekstre ve bakiye teslimatı bütünüyle kabul edilir ya da 422 ile reddedilir.

Geçici ve kalıcı hatalar

Geçici (429, 5xx, ağ hatası): aynı Idempotency-Key ile bekleyip yeniden deneyin; Retry-After varsa ona uyun.
Kalıcı (400, 402, 413, 422): aynı isteği değiştirmeden yeniden göndermek işe yaramaz; details[]e göre düzeltin.