İçeriğe geç

Hatalar ve sınırlar

Hatalar

Hata yanıtının biçimi, API'nin döndürdüğü her hata kodu ve her birinde ne yapmanız gerektiği.

Bir istek başarısız olduğunda yanıt, ne olduğunu söyleyen bir HTTP durum kodu, üzerine karar vereceğiniz bir hata kodu ve iki mesaj taşır. Bu rehber hata yanıtının biçimini, API'nin döndürdüğü her hata kodunu ve hangi hatalarda isteği yeniden denemeniz gerektiğini anlatıyor.

Hata yanıtı#

JSON
{
  "success": false,
  "timestamp": "2026-10-01T09:30:00.123Z",
  "traceId": null,
  "userMessage": "Bu mekanda böyle bir masa bulunamadı.",
  "developerMessage": "The table is not one of this venue's tables.",
  "errorCode": "PUBLIC_API_TABLE_NOT_FOUND",
  "validationErrors": [
    { "field": "tableId", "message": "Not one of this venue's tables.", "attemptedValue": null }
  ],
  "details": null
}
successboolean

İşlemin başarılı olup olmadığı. Hata yanıtında her zaman false.

timestampstring · date-time

Yanıtın yazıldığı an (UTC).

traceIdstringnull olabilir

İsteği Cibusy kayıtlarında bulan kimlik, varsa. Destek ekibine yazarken belirtin.

userMessagestringnull olabilir

Sitenizi kullanan kişiye gösterilebilecek bir cümle, Accept-Language başlığındaki dilde.

developerMessagestringnull olabilir

Sizin için, kayıtlarınıza yazmak üzere, İngilizce. İfadesi değişebilir; ayrıştırmayın.

errorCodestringnull olabilir

Ne yapacağınıza karar vereceğiniz sabit kod: PUBLIC_API_VENUE_NOT_FOUND gibi. Tamamı Hatalar rehberinde.

validationErrorsobject[]null olabilir

Hata isteğin bir kısmıyla ilgiliyse, sorunlu alanlar istek gövdesindeki yollarıyla (lines[1].extraIds). Aksi halde null.

Alan hatası alanları
fieldstring

Sorunlu kısmın istek gövdesindeki yolu: customer.phone, lines[0].quantity.

messagestring

Sorunun kısa açıklaması, İngilizce.

attemptedValueanynull olabilir

Gönderilen değer. Genel API bunu null gönderir.

detailsanynull olabilir

Ek ayrıntı için ayrılmış alan. Genel API bunu null gönderir.

Hız sınırını aşan bir çağrının yanıtı biraz farklıdır: validationErrors ve details taşımaz, beklemeniz gereken süreyi retryAfter alanında söyler. Hız sınırları rehberi bu yanıtı anlatıyor.

Hatayı nasıl karşılamalı#

  • Kararı durum kodu ve errorCode ile verin. Mesajların ifadesi değişebilir; kodlar değişmez.
  • userMessage misafiriniz içindir. Sitenizi kullanan kişiye yazılmış bir cümledir ve olduğu gibi gösterilebilir. Dilini Accept-Language başlığı seçer.
  • developerMessage sizin içindir. İngilizcedir ve kayıtlarınıza yazılmak içindir. İfadesi değişebilir; içeriğine göre karar vermeyin.
  • validationErrors neyin yanlış olduğunu söyler. Hata isteğin bir parçasıyla ilgiliyse o parça, istek gövdesindeki yoluyla adlandırılır: lines[1].extraIds gibi. Formunuzda hatayı ilgili alanın yanında gösterebilirsiniz.
  • traceId dolu geldiğinde saklayın. İsteği Cibusy'nin kayıtlarında bulmayı sağlar; destek için yazarken ekleyin.

Hata kodları#

HTTPKodAnlamı
400VALIDATION_ERROR

Bir parametre ya da JSON gövde okunamadı: UUID olmayan bir değer, bir enum değerlerinden biri olmayan bir ad ya da bozuk JSON. validationErrors alanları adlandırır.

400INVALID_PAGE_NUMBER

cursor 1'den küçük.

400INVALID_PAGE_SIZE

pageSize 1 ile 100 arasında değil.

400PUBLIC_API_IDEMPOTENCY_KEY_INVALID

Idempotency-Key başlığı yok ya da 8 ile 64 arası harf, rakam, - veya _ değil.

400PUBLIC_API_ORDER_INVALID

İstek, sipariş türünün, masanın, müşterinin ya da satırların biçim kurallarına uymuyor. Bulunan her sorun validationErrors içinde.

400PUBLIC_API_PRODUCT_OPTION_INVALID

Bir ekstra ya da çıkarılan malzeme ürünün kendisine ait değil, tekrarlanmış ya da ürünün seçim gruplarını bozuyor.

400PUBLIC_API_RESERVATION_INVALID

Rezervasyon isteği biçim kurallarına uymuyor: saat, kişi sayısı, misafirin adı ya da telefonu eksik ya da hatalı, bir metin fazla uzun. Bulunan her sorun validationErrors içinde, istekteki yoluyla.

400TOO_MANY_GUESTS

Rezervasyon 20 kişiden kalabalık. Daha kalabalık gruplar mekanı arayarak yer ayırtır.

400INVALID_RESERVATION_DATE

İstenen saat geçmişte.

401PUBLIC_API_KEY_MISSING

X-Api-Key başlığı yok.

401PUBLIC_API_KEY_INVALID

Anahtar bozuk, bilinmiyor, iptal edilmiş ya da mekanı hesabını kapatmış. Hepsine tek yanıt verilir; hangisi olduğu söylenmez. Panelde anahtarın listede olup olmadığına bakın.

403PUBLIC_API_SCOPE_MISSING

Anahtar geçerli ama bu çağrının gerektirdiği izinle oluşturulmamış: sipariş çağrıları "Sipariş gönderebilir", rezervasyon çağrıları "Rezervasyon alabilir" iznini ister. İzni paneldeki API anahtarları sayfasından verebilirsiniz; değişiklik anahtarın bir sonraki isteğinde geçerli olur.

404PUBLIC_API_VENUE_NOT_FOUND

Mekan yok ya da bu anahtar ona ulaşamıyor. İkisine aynı yanıt verilir, böylece bir anahtar kendi mekanlarının dışında hangi mekanların olduğunu öğrenemez.

404PUBLIC_API_ORDER_NOT_FOUND

Bu anahtarın ulaştığı bir mekanda, API üzerinden bu kimlikle verilmiş bir sipariş yok.

404PUBLIC_API_RESERVATION_NOT_FOUND

Bu anahtarın ulaştığı bir mekanda, API üzerinden bu kimlikle alınmış bir rezervasyon yok. Mekanın başka bir yoldan aldığı rezervasyon da böyle yanıtlanır.

404PUBLIC_API_TABLE_NOT_FOUND

Masada verilen sipariş mekanın masalarından biri olmayan bir masayı adlandırıyor. Masaları GET /venues/{venueId}/tables ile okuyun.

404PUBLIC_API_PRODUCT_NOT_FOUND

Siparişteki bir ürün ya da porsiyon mekanın menüsünde yok. Menünün kopyasını yenileyin.

409PUBLIC_API_PRODUCT_UNAVAILABLE

Bir ürün şu an sipariş edilemiyor: menüde gizlenmiş, tartıyla satılıyor ya da tükenmiş.

409PUBLIC_API_ORDERING_UNAVAILABLE

Mekanın etkin bir aboneliği yok, bu yüzden sipariş almıyor. Menü okunmaya devam eder.

409PLACE_IS_BUSY

Mekanın mutfağı yoğunluk bildirmiş. Mekan bilgisindeki ordering.busyUntil ne zamana kadar sürdüğünü söyler.

409OUTSIDE_WORKING_HOURS

Mekan şu an kapalı.

409ORDER_CREATION_IN_PROGRESS

Aynı Idempotency-Key ile gelen istek hala işleniyor. İsteği aynı anahtarla yeniden gönderin; siparişi alırsınız.

409PUBLIC_API_RESERVATIONS_UNAVAILABLE

Mekanın etkin bir aboneliği yok, bu yüzden rezervasyon almıyor.

409RESERVATIONS_DISABLED

Mekan rezervasyon almayı kapatmış. Müsaitlik yanıtındaki reservationsEnabled bunu önceden söyler.

409RESERVATION_TOO_SOON

İstenen saate 30 dakikadan az kalmış. Daha geç bir saat seçin.

409RESERVATION_TOO_FAR

İstenen saat 60 günden uzak. Müsaitlik yanıtındaki lastBookableDate son günü söyler.

409RESERVATION_TIME_UNAVAILABLE

Mekan o saatte rezervasyon almıyor: kapalı ya da rezervasyon saatlerinin dışında. Saati müsaitlik yanıtından alın.

409RESERVATION_NOT_CANCELLABLE

Rezervasyon artık iptal edilemez: misafir kapıda karşılanmış, saati gelmiş ya da rezervasyon zaten sonuçlanmış (reddedilmiş, tamamlanmış). Rezervasyondaki canCancel bunu önceden söyler.

409PUBLIC_API_WEBHOOK_NOT_CONFIGURED

Anahtarın webhook adresi yok; test olayı ya da yeni imza sırrı istendiğinde verilir. Adresi paneldeki API anahtarları sayfasından ekleyin.

429RATE_LIMIT_EXCEEDED

Anahtar bütçesini aştı. Retry-After saniye kadar bekleyin.

500INTERNAL_ERROR

Cibusy tarafında bir sorun. Biraz bekleyip tekrar deneyin; siparişi aynı Idempotency-Key ile yeniden gönderin.

Hangi hatalar yeniden denenir#

YanıtNe yapmalı
429 RATE_LIMIT_EXCEEDEDRetry-After başlığındaki saniye kadar bekleyin, sonra tekrar deneyin.
500 INTERNAL_ERRORBir süre bekleyip tekrar deneyin. Siparişi aynı Idempotency-Key ile, rezervasyonu değiştirmeden tekrar gönderin.
409 ORDER_CREATION_IN_PROGRESSKısa bir süre sonra aynı Idempotency-Key ile tekrar gönderin; siparişi alırsınız.
Zaman aşımı ya da kopan bağlantıOkuma isteğini tekrarlayın. Siparişi aynı Idempotency-Key ile tekrar gönderin: sipariş verilmişse onu alırsınız. Rezervasyonu değiştirmeden tekrar gönderin: alınmışsa onu alırsınız.
409 RESERVATIONS_DISABLED, PUBLIC_API_RESERVATIONS_UNAVAILABLEHemen tekrar denemeyin: mekan şu an rezervasyon almıyor. Misafire userMessage ile söyleyin.
409 RESERVATION_TOO_SOON, RESERVATION_TOO_FAR, RESERVATION_TIME_UNAVAILABLEAynı saat aynı yanıtı alır. Müsait saatleri yeniden okuyun ve misafire başka bir saat seçtirin.
409 PLACE_IS_BUSY, OUTSIDE_WORKING_HOURS, PUBLIC_API_ORDERING_UNAVAILABLEHemen tekrar denemeyin: mekan şu an sipariş almıyor. Misafire userMessage ile söyleyin. Mekanın bilgilerindeki ordering.busyUntil, bir yoğunluğun bittiği anı verir.
Diğer 4xx yanıtlarıAynı istek aynı yanıtı alır. İsteği ya da anahtarı düzeltmeden tekrar denemeyin.

Sipariş göndermeyi güvenle yeniden denemenin bütün kuralları Sipariş vermek, rezervasyon göndermeninkiler Rezervasyon almak rehberinde.

Panelin hata kodları#

Şu dört kodu API hiçbir zaman döndürmez; mekanın sahibi panelde anahtarları ve webhook'ları ayarlarken görebilir. Mekanınızın size iletebileceği her kod burada açıklanmış olsun diye listeleniyor:

HTTPKodAnlamı
400PUBLIC_API_KEY_NAME_INVALID

Anahtarın adı 1 ile 60 karakter arasında olmalı.

400PUBLIC_API_WEBHOOK_URL_INVALID

Webhook adresi herkese açık bir https:// adresi olmalı; özel, yerel ya da iç ağdaki adresler kabul edilmez.

404PUBLIC_API_KEY_NOT_FOUND

Panelde değiştirilmek istenen anahtar yok ya da iptal edilmiş.

409PUBLIC_API_KEY_LIMIT_REACHED

Mekanın aynı anda en fazla 10 etkin anahtarı olabilir. Yenisi için kullanılmayan birini iptal edin.