Hata yanıtları

API'de hatalar iki düzeyde ortaya çıkar: isteğin kendisi reddedilir (HTTP hata kodu döner) veya istek kabul edilir ancak asenkron işlem sırasında hata oluşur (fatura kaydındaki errors[] dizisine yazılır).

1. HTTP hata kodları

Kod	Durum	Açıklama
401	Unauthenticated	API anahtarı eksik veya geçersiz. Authorization: Bearer ... başlığını kontrol edin.
403	Forbidden	Hesabınızın bu işlem için yetkisi/kotası yok (örn. fatura oluşturma limiti).
404	Not Found	Kayıt bulunamadı veya hesabınıza ait değil.
422	Unprocessable Entity	Doğrulama hatası; ayrıntılar errors nesnesinde alan bazında döner.
5xx	Server Error	Sunucu hatası; kısa bir bekleme sonrası isteği yineleyin, sürerse destekle iletişime geçin.

422 doğrulama hatası formatı

Gövde alanları doğrulamadan geçemezse istek kaydedilmez ve alan bazında Türkçe mesajlar döner:

{
  "message": "Fatura tipi zorunludur. (and 2 more errors)",
  "errors": {
    "type": ["Fatura tipi zorunludur."],
    "customer.tax_number": ["Müşteri VKN/TCKN 10 veya 11 haneli olmalıdır."],
    "lines.0.unit": ["Seçilen ürün birimi geçersiz."]
  }
}

• errors anahtarları, isteğin gövdesindeki alan yollarıdır; dizi elemanları lines.0.unit gibi indeksle belirtilir.
• Fatura silme gibi sağlayıcıya bağlı işlemlerde sağlayıcı hatası da aynı formatta, errors.api_error anahtarıyla döner.

2. Asenkron işlem hataları (errors[])

POST /api/invoices isteği 2xx dönse bile fatura asenkron işlenir: taslak oluşturma, resmileştirme (GİB'e gönderim) ve PDF adımlarından herhangi biri hata alabilir. Bu durumda:

• workflow_status → failed ve/veya formal_status → failed olur,
• hata ayrıntısı fatura kaydındaki errors[] dizisine eklenir,
• fatura oluştururken callback_url verdiyseniz callback bildirimi tetiklenir.

GET /api/invoices/{id} yanıtındaki errors[] elemanları şu yapıdadır:

{
  "errors": [
    {
      "id": 501,
      "invoice_id": 123,
      "action": "formalize",
      "message": "Alıcı VKN'si geçersiz.",
      "created_at": "2026-07-02T14:31:05.000000Z"
    }
  ]
}

Alan	Açıklama
action	Hatanın oluştuğu adım (örn. findInvoiceType, createDraft, formalize).
message	Sağlayıcıdan veya iş akışından gelen hata mesajı.
created_at	Hatanın kaydedildiği zaman. Kayıtlar en yeniden eskiye sıralı döner.