Hız sınırları ve kotalar

İki tür sınır, API’nin herkes için hızlı kalmasını sağlar:

• Bir anahtarın hız sınırı: kısa süreli yoğunluklar için bir ani artış payıyla birlikte saniyede kaç istek gönderebileceği.
• Kuruluşun kotaları: kuruluşun tüm anahtarlarının birlikte dakikada, günde ve ayda kaç istek gönderebileceği.

İkisi de kuruluşun planına bağlıdır. Her yanıt size ne durumda olduğunuzu söyler; böylece düzgün çalışan bir istemcinin hiçbir zaman tahmin yürütmesi gerekmez.

Bir anahtarın hız sınırı

Her anahtar sabit bir hız ve bir ani artış payı alır. Ani artış payı, o sayıda isteği aynı anda göndermenize izin verir; bundan sonra istekler sabit hızda kabul edilir.

Sınıf, kuruluşun planından gelir. GET /v1/me, kendisini çağıran anahtarın sınıfını, hızını ve ani artış payını gösterir (rate_limit). Sınır, isteklerinize kaç API sunucusu hizmet verirse versin anahtarın tamamı için geçerlidir.

Akış uç noktaları, yani POST /v1/chat ("stream": true ile ya da onsuz) ve GET /v1/jobs/stream, anahtarın hız sınırının dışındadır: onu tüketmezler ve RateLimit başlıklarında "key" öğesi yoktur. Kuruluşun kotalarına ise istek başladığında birer kez sayılırlar. Soruların aşağıda anlatılan kendi sınırları vardır.

Kuruluşun kotaları

Bir plan, kuruluş için dakika, gün ve ay başına istek kotaları belirleyebilir. Zaman pencereleri UTC’deki takvim dönemleridir: dakika :00 saniyede, gün 00:00 UTC’de, ay ayın ilk günü 00:00 UTC’de başlar. Kuruluşa ait bir anahtarla ya da OAuth belirteciyle yapılan her istek, hangi adrese gönderilirse gönderilsin sayılır. Akış isteği, ne kadar sürerse sürsün, başladığında bir kez sayılır; kota tükendiyse diğer tüm istekler gibi 429 ile reddedilir. 429 ile reddedilen istek sayılmaz.

Başlıklar

Anahtarla yapılan bir isteğe verilen her yanıt, o istek için geçerli olan sınırları taşır:

RateLimit-Policy: "key";q=100;w=5, "minute";q=1200;w=60, "day";q=200000;w=86400
RateLimit: "key";r=87;t=1, "minute";r=1150;t=23, "day";r=180311;t=40213
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1

RateLimit-Policy ve RateLimit, RateLimit header fields for HTTP adlı IETF taslağına uyar. Her öğe bir sınırdır:

X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset başlıkları, RateLimit başlığından önce yazılmış istemciler için bu sınırların en katısını daha basit bir biçimde bildirir. X-RateLimit-Reset saniye cinsindendir.

Bir sınıra ulaşıldığında

API, saniye cinsinden bir Retry-After başlığıyla 429 Too Many Requests yanıtı verir:

{
  "detail": "the organization has used its API request quota for this period",
  "error": {
    "code": "api.quota_exceeded",
    "message": "the organization has used its API request quota for this period",
    "details": {"quota": "day", "limit": 200000, "reset_at": "2026-10-25T00:00:00Z", "retry_after": 40213},
    "request_id": "01JB7…"
  }
}

Retry-After süresi kadar bekleyin ve isteği tekrarlayın. POST ve PATCH isteklerini aynı Idempotency-Key ile tekrarlayın. Hatalar sayfasındaki yeniden deneme yardımcıları ikisini de yapar.

Planın diğer sınırları da Retry-After ile 429 yanıtı verir; örneğin günlük soru sayısı (limits.questions) ya da aynı anda hazırlanan yanıt sayısı (limits.concurrent_answers). Bunları da aynı şekilde ele alın.

Sınırların altında kalma

• Bir 429 yanıtını beklemek yerine RateLimit başlığını okuyun ve r azaldığında yavaşlayın.
• Toplu işleri zamana yayın ve varsa toplu gönderim uç noktalarını kullanın: 100 belgelik bir toplu gönderim tek bir istektir.
• Değişiklikleri sık aralıklı bir döngüde yoklamayın. Webhook’lara abone olun ya da olay beslemesini birkaç saniyede bir okuyun.
• Paralel çalışan işçileri ortak bir hız sınırlayıcıyla çalıştırın. Aynı anahtarı kullanan birden fazla süreç tek bir hız sınırını paylaşır.
• Entegrasyonunuz daha fazlasına ihtiyaç duyuyorsa daha yüksek bir sınıf için Sursa’daki irtibat kişinize başvurun.