Başvuru

Hatalar ve sınırlar

Bütün hatalar aynı biçimde döner: makinenin okuyacağı code ve kullanıcıya gösterilebilecek Türkçe message.

Biçim

Hata yanıtı

{
  "error": {
    "code": "KURYE_ALDI",
    "message": "Paket kuryede; iptal için kurye firmasını arayın"
  }
}

Kararı code'a göre verin; message değişebilir. Doğrulama hatasında details hangi alanın neden reddedildiğini taşır.

Kodlar

HTTP	code	Anlamı
400	`DOGRULAMA`	Gövde şemaya uymuyor; details alanında hangi alan ve neden
400	`ESLEME_KODU_GEREKLI`	Yeni restoran için pairing_code gönderilmedi
400	`ESLEME_KODU_GECERSIZ`	Eşleme kodu yanlış, kullanılmış ya da süresi dolmuş
400	`IMLEC_GECERSIZ`	since imleci çözülemedi; imleçsiz yeniden isteyin
401	`invalid_client`	client_id ya da client_secret hatalı (jeton isteğinde)
401	`KIMLIK_YOK · SURESI_DOLDU · GECERSIZ · OTURUM_GECERSIZ`	Jeton yok, süresi dolmuş, bozuk ya da kimlik kapatılmış: yeni jeton alın
403	`YETKI_YOK`	Bu uç kimliğiniz için değil
404	`BULUNAMADI · MAGAZA_YOK`	Kayıt yok ya da size ait değil (başkasının kaydı da 404 döner)
409	`IDEMPOTENCY_CAKISMA`	Aynı Idempotency-Key farklı gövdeyle gönderildi
409	`EXTERNAL_REF_TEKRAR`	Bu restoranda aynı external_ref ile teslimat var; details.delivery_id mevcut teslimatın kimliği
409	`MAGAZA_PASIF`	Restoran askıda ya da kapalı; kurye firmasıyla görüşün
409	`KURYE_ALDI`	Paket kuryede; iptal/değişiklik kurye firmasından
409	`SON_DURUM`	Teslimat zaten bitmiş (teslim, iptal, başarısız, iade)
409	`PLAN_DEGISEMEZ`	Teklif çıktıktan sonra ileri tarih değiştirilemez
409	`BASKA_POS`	Restoran başka bir entegratöre bağlı
409	`ABONELIK_SINIRI`	En çok 5 aktif webhook adresi
410	`TAKIP_KAPANDI`	Takip bağlantısının süresi doldu (teslimden 2 saat sonra)
422	`HIZMET_DISI`	Teslim adresi kurye firmasının hizmet alanı dışında; details = { road_km, max_km }. Yeniden denemeyin, adresi düzeltin
415	`—`	Content-Type application/json değil
429	`HIZ_SINIRI`	İstek sınırı aşıldı; retry-after kadar bekleyin
500	`SUNUCU_HATASI`	Beklenmeyen hata; aynı isteği geri çekilmeyle yeniden deneyin (Idempotency-Key ile güvenli)

Sınırlar

Ne	Sınır
POS jetonuyla gelen istekler (entegratör başına)	Dakikada 1.200 istek; sayaç sunucunuzun IP adresine değil entegratör kimliğinize bağlı
Jetonsuz ve panel istekleri (IP başına)	Dakikada 300 istek
POST /oauth/token	Dakikada 30 (IP başına): jetonu 30 dakika saklayıp yeniden kullanın
GET /v1/public/tracking/{anahtar}	Dakikada 60
Webhook adresi	Kimlik başına 5 aktif
Liste (limit)	İstek başına en çok 200 kayıt
Sipariş kalemi	En çok 200 kalem
Teslim fotoğrafı	Sipariş başına 3, her biri en çok 1,5 MB

Her yanıtta x-ratelimit-limit, x-ratelimit-remaining ve x-ratelimit-reset (saniye) başlıkları gelir; 429'da retry-after.

Yeniden deneme

Ağ hatası, 429, 5xx: üstel geri çekilmeyle (1 sn, 2 sn, 4 sn… en çok 1 dk) yeniden deneyin. Sipariş oluşturmada aynı Idempotency-Key'i gönderin; ikinci teslimat açılmaz.
401: bir kez yeni jeton alıp tekrar deneyin; yine 401 ise kimlik kapatılmış olabilir.
4xx (401 ve 429 dışı): yeniden denemeyin; isteği düzeltin.