Лимити на честотата и квоти

Два вида лимити поддържат API бърз за всички:

• Лимитът на честотата на ключ: колко заявки в секунда може да изпраща той, с пиково натоварване (burst) за кратки пикове.
• Квотите на организацията: колко заявки може да изпратят всички нейни ключове заедно за минута, за ден и за месец.

И двата вида зависят от плана на организацията. Всеки отговор ви казва докъде сте стигнали, затова на добре написания клиент никога не се налага да гадае.

Лимит на честотата на ключ

Всеки ключ получава постоянна честота и пиково натоварване. Пиковото натоварване ви позволява да изпратите толкова заявки наведнъж; след това заявките се допускат с постоянната честота.

Класът идва от плана на организацията. GET /v1/me показва класа, честотата и пиковото натоварване на ключа, който го извиква (rate_limit). Лимитът важи за ключа като цяло, колкото и сървъри на API да обслужват заявките ви.

Операциите с поток, POST /v1/chat (със или без "stream": true) и GET /v1/jobs/stream, са извън лимита на честотата на ключа: те не го изразходват, а заглавките им RateLimit нямат елемент "key". Те се отчитат в квотите на организацията – всяка веднъж, при започването на заявката. Въпросите имат собствени лимити, описани по-долу.

Квоти на организацията

Планът може да задава квоти за заявки на организацията: за минута, за ден и за месец. Прозорците са календарни периоди в UTC: минутата започва в :00 секунди, денят – в 00:00 UTC, месецът – на първия ден в 00:00 UTC. Отчита се всяка заявка с ключ или OAuth токен на организацията, на всеки адрес. Заявка с поток се отчита веднъж, при започването си, колкото и дълго да продължи; при изчерпана квота тя се отказва с 429 като всяка друга заявка. Заявка, отказана с 429, не се отчита.

Заглавките

Всеки отговор на заявка с ключ съдържа лимитите, които важат за нея:

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 и RateLimit следват проекта на IETF RateLimit header fields for HTTP. Всеки елемент е един лимит:

X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset съобщават най-строгия от тези лимити в по-прост вид – за клиентите, написани преди появата на RateLimit. X-RateLimit-Reset е в секунди.

Когато лимитът бъде достигнат

API отговаря с 429 Too Many Requests и заглавка Retry-After в секунди:

{
  "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 и повторете заявката. Повтаряйте POST и PATCH със същия Idempotency-Key. Помощните функции за повторни опити в Грешки правят и двете.

Други лимити на плана също отговарят с 429 и Retry-After, например броят на въпросите на ден (limits.questions) или отговорите, които се подготвят едновременно (limits.concurrent_answers). Обработвайте ги по същия начин.

Как да останете под лимитите

• Четете RateLimit и забавяйте темпото, когато r намалее, вместо да чакате 429.
• Разпределяйте масовата работа във времето и използвайте операциите за пакети, където ги има: един пакет от 100 документа е една заявка.
• Не проверявайте за промени в плътен цикъл. Абонирайте се за уебхукове или четете лентата със събития на всеки няколко секунди.
• Пускайте паралелните обработчици с общ ограничител на честотата. Няколко процеса с един ключ споделят един лимит на честотата.
• Попитайте лицето ви за контакт в Sursa за по-висок клас, ако интеграцията ви има нужда от повече.