Błędy i limity zapytań

Każdy endpoint zwraca błędy w ten sam sposób, więc obsługujesz błędy, limity i ponawianie żądań raz, a następnie używasz tego kodu wszędzie, także przez MCP.

Każda odpowiedź, która nie jest kodem 2xx, to jeden obiekt JSON:

{
  "defined": false,
  "code": "TOO_MANY_REQUESTS",
  "message": "Too many requests",
  "data": { "reason": "rate_limit.exceeded", "retryAfterMs": 12000 }
}

• code to błąd na poziomie HTTP, na przykład UNAUTHORIZED, FORBIDDEN, NOT_FOUND, BAD_REQUEST lub TOO_MANY_REQUESTS.
• data.reason, jeśli występuje, to dokładniejszy, zrozumiały dla maszyny powód, taki jak auth.key_not_found lub rate_limit.exceeded. Rozgałęziaj kod na podstawie tego pola, a nie na podstawie message, które jest przeznaczone dla ludzi i może się zmienić.
• defined to true, gdy operacja wymienia ten błąd w dokumentacji API, oraz false dla błędów, które może napotkać każde żądanie (uwierzytelnianie, limity, nieznana ścieżka).
• Nieudana walidacja zwraca BAD_REQUEST z problemami w data.formErrors i data.fieldErrors.

Każda odpowiedź zawiera również X-Request-ID. Cytuj go, gdy kontaktujesz się z pomocą techniczną, a my odnajdziemy dokładnie to żądanie.

Każda odpowiedź zawiera informacje o limicie, względem którego zostało zliczone żądanie, w dwóch formach:

• nagłówki X-RateLimit-*;
• strukturalne pola IETF RateLimit (aktualny stan: r to liczba pozostałych żądań, t to sekundy do resetu okna) oraz RateLimit-Policy (kwota: q to limit, w to okno w sekundach).

Odpowiedź 429 zawiera również Retry-After w sekundach oraz data.retryAfterMs. Poczekaj co najmniej tyle czasu przed następnym żądaniem; ponowienie próby wcześniej zostanie zliczone i odrzucone ponownie.

Operacja zapisu, która wymienia nagłówek Idempotency-Key w dokumentacji API, może być ponawiana bez ryzyka podwójnego wykonania. Wyślij jeden klucz na logiczną operację zapisu i powtarzaj ten sam klucz przy każdej próbie ponowienia:

• ten sam klucz z tym samym ciałem w ciągu 24 godzin odtwarza zapisaną odpowiedź;
• ten sam klucz z innym ciałem jest odrzucany z kodem 422;
• duplikat, który dotrze, gdy pierwsze żądanie jest jeszcze w trakcie przetwarzania, otrzymuje 409.

Operacja bez tego nagłówka nie jest idempotentna, więc ponawiaj ją tylko wtedy, gdy wiesz, że pierwsza próba nie została zrealizowana.