Hatalar ve sınırlar

Hız sınırları

Anahtar başına iki istek bütçesi, 429 yanıtı ve bütçe içinde kalmanın yolları.

Her API anahtarının dakikalık iki istek bütçesi vardır. Bu rehber bütçeleri, bütçe aşıldığında gelen yanıtı ve bütçenin içinde kalmanın yollarını anlatıyor.

İki bütçe#

Bütçeler sabit, bir dakikalık pencerelerde sayılır:

Çağrılar	Anahtar başına sınır
Mekanları, menüleri, masaları, siparişleri, müsait saatleri ve rezervasyonları okumak; sepeti fiyatlandırmak	Dakikada yaklaşık 120
Sipariş vermek; rezervasyon almak ya da iptal etmek; test webhook'u göndermek	Dakikada yaklaşık 30

İki bütçe birbirinden ayrıdır: menüyü okumak, anahtarın sipariş ve rezervasyon bütçesinden düşmez.
Yeniden denenen bir sipariş ya da rezervasyon da bir çağrı sayılır.
Aynı IP adresinden gelen bütün çağrılar ayrıca, o adresteki diğer her şeyle birlikte dakikada yaklaşık 500 isteklik ortak bir tavanı paylaşır.

Sınırlar neden yaklaşık#

Cibusy birden çok sunucuda çalışır ve her sunucu kendisine gelen çağrıları kendisi sayar. Bu yüzden yük altında bir anahtar bir dakikada 120 ya da 30 çağrıdan biraz fazlasını geçirebilir. Planınızı geçebilecek olana göre değil, yukarıdaki rakamlara göre yapın ve bir 429 yanıtını yavaşlama işareti sayın.

429 yanıtı#

Bütçeyi aşan çağrı sıraya alınmaz. 429 RATE_LIMIT_EXCEEDED ve Retry-After: 60 başlığıyla yanıtlanır; bir sonraki pencere bir dakika içinde açılır.

JSON

{
  "success": false,
  "userMessage": "Bu API anahtarıyla çok fazla istek gönderildi. Bir dakika bekleyip yeniden deneyin.",
  "developerMessage": "Rate limit exceeded for policy. Please retry after 60 seconds.",
  "errorCode": "RATE_LIMIT_EXCEEDED",
  "retryAfter": 60,
  "timestamp": "2026-10-01T09:30:00.123Z",
  "traceId": "0HNF3N1G9B0TO:00000003"
}

successboolean

Her zaman false.

userMessagestring

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

developerMessagestring

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

errorCodestring

Her zaman RATE_LIMIT_EXCEEDED.

retryAfterinteger

Beklenecek saniye. Retry-After başlığıyla aynı.

timestampstring · date-time

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

traceIdstring

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

Retry-After başlığındaki (ya da retryAfter alanındaki) saniye kadar bekleyin, sonra tekrar deneyin. Beklemeden tekrar denemek yalnız bir sonraki 429 yanıtını getirir.

JavaScript

const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function callCibusy(url, options = {}) {
  for (let attempt = 1; ; attempt++) {
    const response = await fetch(url, {
      ...options,
      headers: { ...options.headers, 'X-Api-Key': process.env.CIBUSY_API_KEY },
    });
    if (response.status !== 429 || attempt === 3) return response;

    const seconds = Number(response.headers.get('Retry-After')) || 60;
    await wait(seconds * 1000);
  }
}

Bir arka plan işinde beklemek doğrudur. Bir misafirin isteğini karşılarken ise bir dakika bekletmek yerine ona birazdan tekrar denemesini söyleyin: userMessage bunun için yazılmıştır.

Bütçenin içinde kalmak#

Menünün bir kopyasını tutun. Menüyü her ziyaretçi için okumayın; kopyanızı If-None-Match ile ara sıra doğrulayın. Nasıl yapıldığı Menüyü okumak rehberinde.
Siparişleri ve rezervasyonları webhook'larla izleyin. Açık olanları sürekli sorgulamak yerine webhook kullanın ve yalnız emin olmadığınız bir siparişi ya da rezervasyonu okuyun.
Değişmeyeni tekrar okumayın. Masalar ve mekanın bilgileri sık değişmez. Mekanın ordering durumunu sipariş ekranı açıldığında okumak yeterlidir; siparişin kabul edilip edilmediğini zaten siparişin yanıtı söyler.
Her entegrasyona ayrı bir anahtar verin. Bütçe anahtar başınadır: web siteniz ile bir sipariş kioskunuz ayrı anahtarlar kullanırsa biri diğerinin bütçesini tüketmez.