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ı#
{
"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-timeYanıtın yazıldığı an (UTC).
traceIdstringnull olabilirİsteği Cibusy kayıtlarında bulan kimlik, varsa. Destek ekibine yazarken belirtin.
userMessagestringnull olabilirSitenizi kullanan kişiye gösterilebilecek bir cümle, Accept-Language başlığındaki dilde.
developerMessagestringnull olabilirSizin için, kayıtlarınıza yazmak üzere, İngilizce. İfadesi değişebilir; ayrıştırmayın.
errorCodestringnull olabilirNe yapacağınıza karar vereceğiniz sabit kod: PUBLIC_API_VENUE_NOT_FOUND gibi. Tamamı Hatalar rehberinde.
validationErrorsobject[]null olabilirHata isteğin bir kısmıyla ilgiliyse, sorunlu alanlar istek gövdesindeki yollarıyla (lines[1].extraIds). Aksi halde null.
Alan hatası alanları
fieldstringSorunlu kısmın istek gövdesindeki yolu: customer.phone, lines[0].quantity.
messagestringSorunun kısa açıklaması, İngilizce.
attemptedValueanynull olabilirGönderilen değer. Genel API bunu null gönderir.
detailsanynull olabilirEk 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
errorCodeile verin. Mesajların ifadesi değişebilir; kodlar değişmez. userMessagemisafiriniz içindir. Sitenizi kullanan kişiye yazılmış bir cümledir ve olduğu gibi gösterilebilir. DiliniAccept-Languagebaşlığı seçer.developerMessagesizin içindir. İngilizcedir ve kayıtlarınıza yazılmak içindir. İfadesi değişebilir; içeriğine göre karar vermeyin.validationErrorsneyin 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].extraIdsgibi. Formunuzda hatayı ilgili alanın yanında gösterebilirsiniz.traceIddolu geldiğinde saklayın. İsteği Cibusy'nin kayıtlarında bulmayı sağlar; destek için yazarken ekleyin.
Hata kodları#
| HTTP | Kod | Anlamı |
|---|---|---|
| 400 | VALIDATION_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. |
| 400 | INVALID_PAGE_NUMBER |
|
| 400 | INVALID_PAGE_SIZE |
|
| 400 | PUBLIC_API_IDEMPOTENCY_KEY_INVALID |
|
| 400 | PUBLIC_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 |
| 400 | PUBLIC_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. |
| 400 | PUBLIC_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 |
| 400 | TOO_MANY_GUESTS | Rezervasyon 20 kişiden kalabalık. Daha kalabalık gruplar mekanı arayarak yer ayırtır. |
| 400 | INVALID_RESERVATION_DATE | İstenen saat geçmişte. |
| 401 | PUBLIC_API_KEY_MISSING |
|
| 401 | PUBLIC_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. |
| 403 | PUBLIC_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. |
| 404 | PUBLIC_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. |
| 404 | PUBLIC_API_ORDER_NOT_FOUND | Bu anahtarın ulaştığı bir mekanda, API üzerinden bu kimlikle verilmiş bir sipariş yok. |
| 404 | PUBLIC_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. |
| 404 | PUBLIC_API_TABLE_NOT_FOUND | Masada verilen sipariş mekanın masalarından biri olmayan bir masayı adlandırıyor. Masaları |
| 404 | PUBLIC_API_PRODUCT_NOT_FOUND | Siparişteki bir ürün ya da porsiyon mekanın menüsünde yok. Menünün kopyasını yenileyin. |
| 409 | PUBLIC_API_PRODUCT_UNAVAILABLE | Bir ürün şu an sipariş edilemiyor: menüde gizlenmiş, tartıyla satılıyor ya da tükenmiş. |
| 409 | PUBLIC_API_ORDERING_UNAVAILABLE | Mekanın etkin bir aboneliği yok, bu yüzden sipariş almıyor. Menü okunmaya devam eder. |
| 409 | PLACE_IS_BUSY | Mekanın mutfağı yoğunluk bildirmiş. Mekan bilgisindeki |
| 409 | OUTSIDE_WORKING_HOURS | Mekan şu an kapalı. |
| 409 | ORDER_CREATION_IN_PROGRESS | Aynı |
| 409 | PUBLIC_API_RESERVATIONS_UNAVAILABLE | Mekanın etkin bir aboneliği yok, bu yüzden rezervasyon almıyor. |
| 409 | RESERVATIONS_DISABLED | Mekan rezervasyon almayı kapatmış. Müsaitlik yanıtındaki |
| 409 | RESERVATION_TOO_SOON | İstenen saate 30 dakikadan az kalmış. Daha geç bir saat seçin. |
| 409 | RESERVATION_TOO_FAR | İstenen saat 60 günden uzak. Müsaitlik yanıtındaki |
| 409 | RESERVATION_TIME_UNAVAILABLE | Mekan o saatte rezervasyon almıyor: kapalı ya da rezervasyon saatlerinin dışında. Saati müsaitlik yanıtından alın. |
| 409 | RESERVATION_NOT_CANCELLABLE | Rezervasyon artık iptal edilemez: misafir kapıda karşılanmış, saati gelmiş ya da rezervasyon zaten sonuçlanmış (reddedilmiş, tamamlanmış). Rezervasyondaki |
| 409 | PUBLIC_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. |
| 429 | RATE_LIMIT_EXCEEDED | Anahtar bütçesini aştı. |
| 500 | INTERNAL_ERROR | Cibusy tarafında bir sorun. Biraz bekleyip tekrar deneyin; siparişi aynı |
Hangi hatalar yeniden denenir#
| Yanıt | Ne yapmalı |
|---|---|
429 RATE_LIMIT_EXCEEDED | Retry-After başlığındaki saniye kadar bekleyin, sonra tekrar deneyin. |
500 INTERNAL_ERROR | Bir süre bekleyip tekrar deneyin. Siparişi aynı Idempotency-Key ile, rezervasyonu değiştirmeden tekrar gönderin. |
409 ORDER_CREATION_IN_PROGRESS | Kı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_UNAVAILABLE | Hemen tekrar denemeyin: mekan şu an rezervasyon almıyor. Misafire userMessage ile söyleyin. |
409 RESERVATION_TOO_SOON, RESERVATION_TOO_FAR, RESERVATION_TIME_UNAVAILABLE | Aynı 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_UNAVAILABLE | Hemen 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:
| HTTP | Kod | Anlamı |
|---|---|---|
| 400 | PUBLIC_API_KEY_NAME_INVALID | Anahtarın adı 1 ile 60 karakter arasında olmalı. |
| 400 | PUBLIC_API_WEBHOOK_URL_INVALID | Webhook adresi herkese açık bir |
| 404 | PUBLIC_API_KEY_NOT_FOUND | Panelde değiştirilmek istenen anahtar yok ya da iptal edilmiş. |
| 409 | PUBLIC_API_KEY_LIMIT_REACHED | Mekanın aynı anda en fazla 10 etkin anahtarı olabilir. Yenisi için kullanılmayan birini iptal edin. |