Ana içeriğe geç

Hata Kodları

Hatalar JSON gövdeyle döner:

{
  "message": "ERROR_INSUFFICIENT_SCOPE",
  "status_code": 403
}

Doğrulama hataları alan bazında ayrıntı taşır:

{
  "message": "ERROR_VALIDATION",
  "status_code": 400,
  "errors": [
    { "field": "buyer", "message": "ERROR_REQUIRED_FIELD" }
  ]
}

HTTP durumları​

KodAnlamıNe yapmalı
200Başarılı — kayıt zaten mevcuttuTekrarlı gönderim. Hata değil.
201Oluşturuldu—
400Geçersiz istekGövdeyi düzeltin, tekrar denemeyin.
401Kimlik doğrulanamadıAnahtar/token geçersiz, süresi geçmiş ya da iptal edilmiş.
403Yetki yokScope eksik ya da uç makine erişimine kapalı.
404BulunamadıBelge yok ya da başka bir mükellefe ait — sizin yerel ID'niz değil, bizim döndürdüğümüz kimliği (belge UUID'si / ETTN) kullanın.
412Mükellef hazır değilMükellefin e-belge kurulumu tamamlanmamış.
402Kontör/lisans yetersizKontör bitmiş ya da lisans süresi dolmuş.
422İşlenemediİçerik geçerli ama mevzuat/veri tutarsız.
429Çok fazla istekBekleyip tekrar deneyin.
500Bizden kaynaklı hataTekrar deneyin; sürerse bize bildirin.
503Sağlayıcı erişilemiyorGeçici. Artan aralıklarla tekrar deneyin.

Sık karşılaşılanlar​

ERROR_IDEMPOTENCY_KEY_REQUIRED (400)​

Fatura kesme ucunda Idempotency-Key başlığı zorunludur. Sipariş kimliğinizi kullanın.

ERROR_IDEMPOTENCY_KEY_TOO_LONG (400)​

Anahtar 128 karakteri aşıyor; sağlayıcıya hiç gitmeden kapıda reddedilir. Daha kısa, mükellef bazında tekil bir anahtar kullanın. Bkz. Eşleştirme.

ERROR_IDEMPOTENCY_KEY_INVALID (400)​

Anahtarda boşluk, satır sonu ya da çok baytlı (örn. Türkçe) bir karakter var. İzinli küme: boşluksuz basılabilir ASCII. Sebep, anahtarın ETTN'e bayt olarak girmesi — bkz. Eşleştirme.

ERROR_VALIDATION — buyer / ERROR_REQUIRED_FIELD (400)​

Satış oluşturma ucunda buyer hiç gönderilmemiş; gövde doğrulaması alan bazında düşer. Alıcı belgenin fatura alıcısıdır ve satışın üzerine yazılır; alıcısız bir belge kesilemez. Bkz. Alıcı bilgisi nerede durur.

ERROR_BUYER_TITLE_REQUIRED (400)​

buyer var ama belgeye yazılacak bir unvan/ad soyad yok. TCKN/VKN zorunlu değildir — kanalınız tutmuyor olabilir — ama title (ya da contact_name) şarttır.

ERROR_SALE_REQUIRED_BEFORE_INVOICE (400)​

Fatura kesme ucu satışa bağlanmamış belge kabul etmez: ciro raporu ve stok bu bağdan işler. Önce satışı oluşturun, dönen transaction_id'yi transaction_header_id olarak geçirin.

Tek istisna iadedir: canonical.InvoiceTypeCode = IADE, TEVKIFATIADE ya da YTBIADE gönderdiğinizde satış bağı aranmaz — iade kendi belgesidir ve satışa bağlanırsa aynı satış iki kez sayılır. Buna karşılık iade, asıl fatura atfı ister (bkz. ERROR_INVOICE_RETURN_NEEDS_REFERENCE).

ERROR_INVALID_DOCUMENT_TYPE (400)​

document_type tanımlı değerlerden biri olmalıdır: EFATURA, EARSIV, EIRSALIYE, ESMM, EMM, EADISYON.

ERROR_ORDER_LINES_EMPTY (400)​

Satış oluşturma ucuna satırsız ("lines": []) gövde gelmiş. En az bir satır şart.

ERROR_EXCHANGE_RATE_REQUIRED (400)​

Dövizli belge, TL karşılığının türetildiği kur olmadan kesilemez.

Satış ucunda bu hatayı yalnızca TCMB bülteni o para birimini taşımıyorsa alırsınız: exchange_rate göndermediğinizde kuru biz dolduruyoruz. Kur uydurulmaz — kendi kurunuzu gönderin. Bkz. Döviz ve kur.

İade ucunda asıl satışın kuru okunamadığında gelir; satışın taşıdığı exchange_rate'i gönderin.

Fatura ucunda canonical.Currency TRY değil ama ExchangeRate yok demektir.

ERROR_EXCHANGE_RATE_UNAVAILABLE (503)​

TCMB bültenine hiç erişilemedi. Geçicidir, tekrar deneyebilirsiniz; ya da kendi kurunuzu exchange_rate ile gönderip beklemeyin.

ERROR_INVOICE_ZERO_VAT_NEEDS_EXEMPTION (400)​

Belgede %0 KDV'li satır var ama istisna sebebi yok. GİB şematronu sebebi olmayan %0 KDV'li satırı reddediyor.

Satış ucunda invoice_exemption_code + invoice_exemption_reason gönderin (bkz. KDV istisnası); fatura ucunda satırın TaxExemptionReasonCode + TaxExemptionReason alanlarını doldurun.

Satış bu hata yüzünden kaybolmaz: istisnasız gönderdiğiniz sipariş kaydedilir, yalnız faturası bekler ve mükellef kodu panelden seçerek kesebilir.

ERROR_INVOICE_EXEMPTION_INVALID_CODE (400)​

İstisna kodu 2xx (kısmi) ya da 3xx (tam) biçiminde olmalıdır. Listede olmayan bir kod reddedilmez — yalnız biçim kontrol edilir.

ERROR_INVOICE_WITHHOLDING_INVALID_CODE (400)​

Tevkifat kodu 6xx (kısmi) ya da 8xx (isteğe bağlı tam) olmalıdır. En sık sebebi kodun yanlış alana yazılmasıdır: 8xx kodları özel matrahta da bulunur ama farklı bir alandır (TaxBaseCode).

ERROR_INVOICE_TAX_BASE_INVALID_CODE (400)​

Özel matrah sebep kodu 8xx olmalıdır (KDVK md. 23). Tevkifatın 6xx kodları burada geçersizdir.

ERROR_INVOICE_RETURN_NEEDS_REFERENCE (400)​

İade faturası (IADE, TEVKIFATIADE, YTBIADE) asıl fatura atfı olmadan kesilemez: GİB şematronu cac:BillingReference şart koşuyor.

canonical.return_info gönderin — anahtar snake_case, ReturnInfo yazımı sessizce düşer. Bkz. İade faturası.

Satışa bağlı kesimde atıf satıştan çözülür; bu hatayı yalnız iade tipini kendiniz gönderip atıf vermediğinizde görürsünüz.

ERROR_ORDER_NOT_IMPORTED (400)​

İade ettiğiniz order_external_id bize hiç aktarılmamış. İade, asıl satış olmadan kurulamaz — önce siparişi aktarın.

ERROR_UNAUTHORIZED (401)​

Anahtar/token yok, geçersiz, süresi geçmiş ya da iptal edilmiş.

ERROR_INSUFFICIENT_SCOPE (403)​

Anahtar/token bu işlem için gereken scope'a sahip değil. Satış oluşturma ve fatura kesme invoice:write, okuma invoice:read ister.

ERROR_API_KEY_NOT_ALLOWED (403)​

Bu uç API anahtarıyla çağrılamaz. Mükellefin e-belge kimlik bilgileri, onboarding ve sağlayıcı ayarları yalnızca panel oturumundan yönetilir — entegrasyonların bu uçlara erişimi bilerek kapalıdır.

ONBOARDING_NOT_STARTED / CONTRACT_PENDING / ONBOARDING_FAILED (412)​

Mükellefin e-belge kurulumu tamamlanmamış. Fatura kesilemez, ama satış oluşturmak çalışır. Mükellefi panelden kurulumu tamamlamaya yönlendirin; biriken satışları sonradan faturalandırabilir. Bu durumu 412 alarak öğrenmek zorunda değilsiniz — Hesap Durumu ucuyla önden sorgulayabilirsiniz.

ERROR_INSUFFICIENT_KONTOR (402)​

Mükellefin kontörü yetersiz. Fatura kesilemez; mükellef panelden kontör yükler ya da Hesap Durumu ucundaki can_topup_in_app alanına göre uygulamanızda bir uyarı gösterin.

license_required (402)​

Mükellefin lisansı bitmiş. Mükellefi panele yönlendirin.

feature_not_enabled (403)​

Hesapta e-Belge modülü tanımlı değil; yanıt feature alanıyla hangi özelliğin eksik olduğunu belirtir.

ERROR_INVOICE_REJECTED_BY_PROVIDER (422)​

E-belge sağlayıcısı belgeyi reddetti — kesinti değil, içerik sorunudur. Gövde ret sebebini taşır:

{
  "message": "ERROR_INVOICE_REJECTED_BY_PROVIDER",
  "status_code": 422,
  "provider_code": "40",
  "provider_message": "Schematron INVOICE: Vergi miktarı 0 olan 0015 vergi kodlu KDV için cbc:TaxExemptionReason elemanı bulunmalıdır."
}
Alanİçerik
provider_codeSağlayıcının hata kodu (40 şema/iş kuralı, 99 sağlayıcı iç hatası, ...)
provider_messageRet sebebi, sağlayıcının kendi metniyle

Tekrar denemeyin — belge düzeltilmeden hiçbir deneme geçmez. Satış kaydı durur; düzeltip aynı Idempotency-Key ile yeniden gönderebilir ya da mükellefin panelden kesmesini bekleyebilirsiniz.

Ret sebebini log'layın

Entegrasyonunuz yalnız HTTP kodunu okuyup provider_message alanını atıyorsa destek turu uzar. Bu iki alanı hata kaydınıza geçirin.

ERROR_INVOICE_NOT_READABLE (400)​

Belge indirme ucunda (/download) görülür: belge yalnızca DRAFT ya da FAILED durumunda ve henüz indirilebilir içerik üretilmemiş. Bkz. Fatura İndir.

ERROR_INVOICE_XML_UNAVAILABLE (400)​

Belge indirme ucunda yalnız format=xml ile görülür: çok eski bir belgede kanonik içerik saklanmamış, XML yeniden üretilemiyor. Tahmin üretmek yerine açıkça reddedilir. PDF/HTML formatları bu belgede yine çalışır.

ERROR_INVOICE_NOT_CANCELLABLE (400)​

İptal ucunda görülür: belge QUEUED / ISSUED / ACCEPTED dışında bir durumda (zaten iptal edilmiş olabilir — bunu "başarılı, zaten iptal" olarak ele alın) ya da e-Fatura ACCEPTED sonrası iptal denemesi. Bkz. Fatura İptal.

all gateway providers failed: ... (503)​

E-belge sağlayıcısına ulaşılamadı. Satışınız kaydedilmiş durumdadır; yalnızca fatura kesimi başarısız olmuştur. Tekrar deneyebilir ya da mükellefin panelden kesmesini bekleyebilirsiniz.

Tekrar deneme​

DurumTekrar denenmeli mi
400, 403, 404, 412, 422❌ İstek düzeltilmeden tekrar denemeyin
401❌ Önce kimlik bilgisini yenileyin
402❌ Mükellef kontör yükleyene/lisansı yenileyene kadar
429, 500, 503✅ Artan aralıklarla (1s, 2s, 4s, 8s…)

external_id ve Idempotency-Key gönderdiğiniz sürece tekrar denemeler güvenlidir: mükerrer satış oluşmaz, ikinci fatura kesilmez, kontör iki kez düşmez.

Yardım​

Çözemediğiniz bir durumda invoice_id / transaction_id / external_id ve isteğin zaman damgasıyla birlikte [email protected] adresine yazın.