İçeriğe geç
KuryeSoft

Kaynaklar

Hatalar

Başarısız her istek uygun HTTP kodunu ve aynı biçimde bir hata gövdesini döndürür. Davranışınızı iletiye değil, code değerine göre belirleyin.

Hata biçimi

404 · application/json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Sipariş bulunamadı"
  }
}
error.code
Açıklama:Makine tarafından okunacak sabit kod. Değişmez; yenileri eklenebilir.
error.message
Açıklama:Türkçe, kullanıcıya gösterilebilir açıklama. Metni değişebilir; koşul yazarken kullanmayın.
error.fields
Açıklama:Yalnızca VALIDATION hatasında: alan yolu → ileti. İç içe alanlar noktayla yazılır (address.text, items.0.name).

Doğrulama hataları

Eksik ya da hatalı alanlar 422 VALIDATION döner. message ilk hatayı, fields bütün hatalı alanları içerir; formunuzda ilgili alanın yanında gösterebilirsiniz.

422 · application/json
{
  "error": {
    "code": "VALIDATION",
    "message": "external_id: Geçersiz değer: beklenen string, alınan undefined",
    "fields": {
      "external_id": "Geçersiz değer: beklenen string, alınan undefined",
      "address.lat": "Çok büyük: beklenen number <=90",
      "total_amount": "Çok küçük: beklenen number >=0"
    }
  }
}

Firmanın ayarlarından kaynaklanan bazı doğrulamalar alan adını iç adla verir; örneğin "Müşteri telefonu zorunlu" ayarı customer.phone yerine customer_phone anahtarıyla döner.

Bütün kodlar

401API_KEY_REQUIRED

İstekte API anahtarı yok ya da ks_ ile başlamıyor.

X-Api-Key başlığını ekleyin.

401API_KEY_INVALID

Anahtar yanlış, silinmiş ya da pasif.

Kurye firmanızdan yeni anahtar isteyin. Yeniden denemeyin.

403FORBIDDEN

İşlem kurye firmasının ayarlarıyla kapalı (ör. sipariş bu aşamada işletme tarafından iptal edilemez).

Kullanıcıya iletiyi gösterin; gerekirse kurye firmasıyla iletişime geçilir.

404NOT_FOUND

Sipariş ya da işletme bulunamadı. Anahtarınızın göremediği bir işletmenin siparişi de böyle görünür.

{ref} değerini ve işletme bilgisini denetleyin.

409ALREADY_CANCELLED

Sipariş zaten iptal edilmiş.

Başarılı sayabilirsiniz; siparişi iptal olarak işaretleyin.

400ORDER_FINAL

Sipariş sonuçlanmış (teslim edildi, teslim edilemedi); değiştirilemez.

Siparişin son durumunu GET /orders/{ref} ile alın.

400OUT_OF_RANGE

Adres, firmanın tanımladığı en fazla teslimat mesafesinin dışında.

Siparişi kurye firmasına göndermeyin; müşteriye bildirin.

400OUT_OF_ZONE

Adres hizmet bölgesinin dışında ya da ücret hesaplanamadı (çoğu zaman konum eksik).

Konum gönderdiğinizden emin olun; POST /quote ile önceden sınayın.

400PAYMENT_TYPE_NOT_FOUND

payment.kind türünde etkin bir ödeme tipi tanımlı değil.

GET /payment-types listesinden payment_type_id gönderin.

400RESTAURANT_INACTIVE

İşletme pasif durumda; sipariş alınmıyor.

Kurye firmasıyla iletişime geçin.

400OPEN_ORDER_LIMIT

İşletmenin aynı anda açık sipariş sınırı doldu.

Açık siparişlerden biri sonuçlanınca tekrar deneyin.

400CREDIT_LIMIT

İşletmenin cari borcu firmanın belirlediği sınırı aştı.

Kurye firmasıyla hesabı kapatın.

422VALIDATION

Eksik ya da hatalı alan. Hangi alanın neden reddedildiği fields içinde yazar.

İsteği düzeltin; aynı haliyle yeniden göndermeyin.

400INVALID_JSON

Gövde geçerli bir JSON değil.

Gövdeyi ve Content-Type: application/json başlığını denetleyin.

413BODY_TOO_LARGE

Gövde 2 MB'tan büyük.

Ürün listesini kısaltın.

429RATE_LIMITEDyeniden denenebilir

Dakikalık istek sınırı aşıldı.

retry-after saniye bekleyip tekrar deneyin.

500INTERNALyeniden denenebilir

Sunucuda beklenmeyen bir hata oluştu.

Kısa bir beklemeyle tekrar deneyin; sürerse kurye firmanıza bildirin.

Ne zaman yeniden denenir

  • Yeniden deneyin: 429, 5xx, zaman aşımı ve bağlantı hataları. Artan aralıklarla (ör. 1, 2, 4, 8 saniye) ve en çok birkaç kez.
  • Yeniden denemeyin: 400, 401, 403, 404, 409, 422. Aynı istek aynı sonucu verir; isteği düzeltin ya da durumu kullanıcıya bildirin.
İpucu:

Sipariş oluştururken yeniden denemek güvenlidir: aynı external_id ikinci sipariş açmaz. Bkz. Yinelenen gönderim.