Limity wywołań

#Limit

Każdy klucz może wykonać 120 wywołań na minutę. REST API i serwer MCP liczą się w tym samym oknie, więc asystent AI i synchronizacja korzystające z jednego klucza dzielą jego limit. Daj każdemu z nich osobny klucz.

Synchronizacja, która odczytuje 500 uczestników na stronę, mieści w limicie 60 000 uczestników, więc dobrze zbudowana integracja rzadko go osiąga. Pętla, która w kółko pyta o to samo, osiągnie go w ciągu minuty – i właśnie po to on jest.

#Ile ci zostało

Każda odpowiedź, również odmowa, podaje limit w dwóch postaciach: w nagłówkach RateLimit według IETF oraz w nagłówkach X-RateLimit-*, które odczytuje większość bibliotek klienckich.

HTTP/1.1 200 OK
RateLimit-Policy: "default";q=120;w=60
RateLimit: "default";r=117;t=42
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 42

r (remaining) to liczba wywołań pozostałych w tym oknie, a t to liczba sekund do rozpoczęcia nowego okna.

#Po przekroczeniu limitu

Wywołanie zostaje odrzucone z 429 Too Many Requests, nagłówkiem Retry-After w sekundach i problemem z "code": "rateLimited". Nic nie zostało wykonane: odczekaj i wyślij je ponownie. Odrzucone wywołanie jest widoczne w aktywności kluczy, więc sprawdzisz, kiedy to się stało.

HTTP/1.1 429 Too Many Requests
Retry-After: 18
Content-Type: application/problem+json

{ "status": 429, "code": "rateLimited", "detail": "This key made more than 120 calls in a minute. Try again in 18 seconds; the RateLimit header says what is left." }

#Jak trzymać się z dala od limitu

• Pobieraj duże strony: limit=500 to nic złego.
• Synchronizuj z updatedSince, zamiast za każdym razem odczytywać wszystko (Stronicowanie i synchronizacja).
• O tym, co właśnie się wydarzyło, dowiaduj się z webhooków, a nie przez odpytywanie.
• Wysyłaj If-None-Match z posiadanym ETagiem: odpowiedź 304 jest szybka, choć nadal się liczy.
• Zrób przerwę, gdy wartość r w RateLimit spada, zamiast czekać na odmowę.

Okno jest liczone osobno na każdym serwerze, więc w bardzo pracowity dzień klucz może od czasu do czasu dostać nieco więcej, niż wynosi limit. Nie polegaj na tym: traktuj nagłówki jako jedyne źródło prawdy.