Hatalar

Gövdenin şekli

Başarılı yanıtlar data ve meta taşır:

{ "data": { }, "meta": { "request_id": "01JB2K9X7Q" } }

Hatalı yanıtlarda data yoktur:

{
  "error": {
    "code": "b2b.delivery_not_cancellable",
    "message": "b2b: delivery cannot be cancelled in current state",
    "field": "status"
  },
  "request_id": "01JB2K9X7Q"
}

Alan	Açıklama
error.code	Makine tarafından okunacak kod. Buna göre dallanın, mesaja göre değil
error.message	İnsan için açıklama. Metni değişebilir
error.field	Hata belirli bir alandaysa adı (isteğe bağlı)
error.details	Ek bağlam (isteğe bağlı)
request_id	Bu isteğin kimliği

request_id değerini loglayın

Destek istediğinizde ilk sorulacak şey budur. Onunla kaydı doğrudan buluruz.

Ortak durum kodları

Kod	Anlamı	Ne yapmalısınız
400	Gövde JSON olarak çözülemedi ya da alan kuralları tutmadı (validation.invalid_json, validation.failed — hangi alan olduğu error.details içinde)	İsteği düzeltin; tekrar denemek işe yaramaz
401	Kimlik geçersiz	Anahtarı ve başlığı kontrol edin
403	Kimlik geçerli, yetki yetersiz	Anahtarın rolü/scope'u bu uç için uygun değil
404	Kayıt yok ya da sizin değil	İkisi ayırt edilmez
409	Kaydın durumu bu işleme izin vermiyor	Durumu okuyup yeniden karar verin
422	İş kuralı reddi: izinsiz durum geçişi, onaysız entegratör, beyan dışı webhook adresi, menü doğrulaması	Kurala bakın; istek değişmeden sonuç değişmez
429	Hız sınırı ya da kota aşıldı	Retry-After kadar bekleyin
5xx	Bizim tarafımızda bir sorun	Artan aralıklarla yeniden deneyin

Kod sözlüğü

error.code değerine göre dallanın, mesaja göre değil.

POS API

Kod	HTTP	Ne yapmalısınız
pos.auth.missing	401	Authorization başlığı yok
pos.auth.invalid	401	Anahtar geçersiz/iptal/süresi dolmuş, restoran askıda, entegratör anlaşması kapanmış ya da anahtar başka ortama ait — hepsi aynı yanıt
pos.gate.unavailable	503	Yetki kontrolü geçici yapılamıyor. Anahtarı yenilemeyin, bekleyin
pos.rate_limit.exceeded	429	Anahtar başına dakikalık sınır; Retry-After kadar bekleyin
pos.quota.exceeded	429	Günlük kota (test anahtarı); Retry-After gün sonuna kadar
pos.scope_missing	403	Rol bu işleme yetmiyor (read_mirror ile menü yazmak)
pos.menu_invalid	422	Menü gövdesi kurallara uymuyor (limitler: POS menü)
pos.source_required	422	İlk importta source zorunlu
pos.source_mismatch	409	source mevcut entegratörle çelişiyor
pos.menu_not_pos_managed	409	Menü henüz POS-yönetimli değil; taslak onayı bekleniyor
pos.item_not_mapped	404	external_id eşleşmiyor
pos.item.invalid	400	Tek ürün gövdesi geçersiz
invalid_transition	422	İzinsiz durum geçişi (⚠️ pos. ön eki yok)
order.not_paid	409	Online ödeme onaylanmadan sipariş kabul edilemez

Test ortamı

Kod	HTTP	Ne yapmalısınız
sandbox.invalid_scenario	400	payment_method / courier_type değeri tanınmıyor
sandbox.menu_empty	409	Önce PUT /pos/menu ile menü yazın

Webhook (restoran)

Kod	HTTP	Ne yapmalısınız
integrator.required	422	Entegratör seçilmedi
integrator.not_approved	422	Entegratörün aktif anlaşması yok
webhook.host_not_allowed	422	Adres entegratörün bildirdiği alan adlarından biri değil
webhook.host_allowlist_missing	422	Entegratörün adres beyanı Veni'de tanımlı değil — adresi değiştirmek çözmez
webhook.ping_unavailable	503	Deneme yolu şu an kullanılamıyor; bekleyin
webhook.ping_rate_limited	429	Saatlik deneme sınırı (10)
webhook.mirror_missing	409	Abonelik kaydı bulunamadı; destek ile görüşün

Partner API

Kod	HTTP	Ne yapmalısınız
b2b.auth.missing	401	Authorization başlığı yok
b2b.auth.invalid	401	Anahtar geçersiz/iptal/süresi dolmuş, partner askıda ya da IP allowlist dışı — beşi de aynı yanıt
b2b.partner_not_active	403	Partner hesabı aktif değil
b2b.scope.insufficient	403	Anahtarın bu uç için yetkisi yok
b2b.partner_not_found	404	Partner yok
b2b.delivery_not_found	404	Teslimat yok ya da sizin değil
b2b.delivery_not_cancellable	409	Bu durumda iptal edilemez
b2b.out_of_range	422	Mesafe hizmet kapsamı dışında
b2b.payment_declined	402	Ödeme reddedildi
b2b.payment_unavailable	503	Ödeme şu an alınamıyor
b2b.rate_limit	429	Partner dakikalık sınırı
b2b.quota_exceeded	429	Günlük kota (tanımlıysa)
b2b.webhook_secret_required · b2b.invalid_webhook_url · b2b.invalid_status · b2b.invalid_allowlist	400	Yönetim gövdesi geçersiz

Ortak

Kod	HTTP	Ne yapmalısınız
validation.invalid_json	400	Gövde JSON olarak çözülemedi
validation.failed	400	Alan kuralları tutmadı; ayrıntı error.details içinde
rate_limit.exceeded	429	Kaynak IP başına sınır (anahtar başına olandan ayrı)

401 neden ayrıntı vermez

Anahtar geçersiz, iptal edilmiş, süresi dolmuş ya da hesap askıda — hepsi aynı yanıtı verir. Hangisi olduğunu söylemek, anahtar deneyen birine "bu anahtar bir zamanlar geçerliydi" bilgisini vermek olurdu.

Kendi anahtarınızı yönetirken bu ayrımı panelden görürsünüz; last_used_at alanı anahtarın gerçekten çalışıp çalışmadığını söyler.

Yeniden denenebilir mi

Durum	Yeniden dene
400 · 403 · 404 · 422	Hayır. İstek değişmeden sonuç değişmez
401	Bir kez, anahtarı yeniledikten sonra
409	Durumu okuyup yeni bir karar verdikten sonra
429	Evet, Retry-After kadar bekleyip
5xx	Evet, artan aralıklarla

Teslimat açarken (POST /api/v1/b2b/deliveries) her yeniden denemede aynı Idempotency-Key değerini gönderin; yenisini üretmek iki teslimat açma riskidir (ayrıntı).