Limity częstotliwości i przydziały

Dwa rodzaje limitów sprawiają, że API działa szybko dla wszystkich:

• Limit częstotliwości klucza: ile żądań na sekundę klucz może wysłać, z chwilowym szczytem (burst) na krótkie skoki ruchu.
• Przydziały organizacji: ile żądań wszystkie jej klucze razem mogą wysłać na minutę, na dzień i na miesiąc.

Oba zależą od planu organizacji. Każda odpowiedź informuje, ile jeszcze możesz wysłać, więc poprawnie działający klient nigdy nie musi zgadywać.

Limit częstotliwości klucza

Każdy klucz ma stałe tempo i chwilowy szczyt. Szczyt pozwala wysłać naraz tyle żądań, ile wynosi; potem żądania są dopuszczane w stałym tempie.

Klasa wynika z planu organizacji. GET /v1/me pokazuje klasę, tempo i szczyt klucza, który wywołuje tę operację (rate_limit). Limit obowiązuje klucz jako całość, niezależnie od tego, ile serwerów API obsługuje Twoje żądania.

Operacje strumieniowe, POST /v1/chat (z "stream": true lub bez) i GET /v1/jobs/stream, są poza limitem częstotliwości klucza: nie zużywają go, a ich nagłówki RateLimit nie mają elementu "key". Liczą się natomiast do przydziałów organizacji, każda raz, w chwili rozpoczęcia żądania. Pytania mają własne limity, opisane niżej.

Przydziały organizacji

Plan może ustalać przydziały żądań dla organizacji: na minutę, na dzień i na miesiąc. Okna to okresy kalendarzowe w UTC: minuta zaczyna się w sekundzie :00, dzień o 00:00 UTC, a miesiąc pierwszego dnia o 00:00 UTC. Liczy się każde żądanie z kluczem lub tokenem OAuth organizacji, wysłane na dowolny adres. Żądanie strumieniowe liczy się raz, w chwili rozpoczęcia, bez względu na to, jak długo trwa; po wyczerpaniu przydziału jest odrzucane z 429 jak każde inne żądanie. Żądanie odrzucone z 429 się nie liczy.

Nagłówki

Każda odpowiedź na żądanie z kluczem zawiera limity, które tego żądania dotyczą:

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 i RateLimit są zgodne z projektem IETF RateLimit header fields for HTTP. Każdy element to jeden limit:

X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset podają najostrzejszy z tych limitów w prostszej formie, dla klientów napisanych, zanim powstał RateLimit. X-RateLimit-Reset jest podawany w sekundach.

Gdy limit zostanie osiągnięty

API odpowiada 429 Too Many Requests z nagłówkiem Retry-After w sekundach:

{
  "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…"
  }
}

Odczekaj czas z Retry-After i powtórz żądanie. POST i PATCH powtarzaj z tym samym Idempotency-Key. Funkcje pomocnicze do ponawiania z przewodnika Błędy robią jedno i drugie.

Inne limity planu również odpowiadają 429 z Retry-After, np. liczba pytań na dzień (limits.questions) lub liczba odpowiedzi w toku w tym samym czasie (limits.concurrent_answers). Obsługuj je tak samo.

Jak nie przekraczać limitów

• Odczytuj RateLimit i zwalniaj, gdy r robi się niskie, zamiast czekać na 429.
• Rozkładaj pracę masową w czasie i używaj operacji pakietowych tam, gdzie istnieją: jeden pakiet 100 dokumentów to jedno żądanie.
• Nie odpytuj o zmiany w ciasnej pętli. Subskrybuj webhooki albo odczytuj kanał zdarzeń co kilka sekund.
• Uruchamiaj równoległe procesy robocze ze wspólnym ogranicznikiem. Kilka procesów z jednym kluczem dzieli jeden limit częstotliwości.
• Jeśli Twoja integracja potrzebuje więcej, zapytaj swoją osobę kontaktową w Sursie o wyższą klasę.