Błędy i ponawianie

Błędy są zwracane jako JSON ze stabilnym, czytelnym maszynowo kodem error i odpowiadającym statusem HTTP.

{
  "error": "rate_limited",
  "message": "Too many requests.",
  "retry_after_ms": 850
}

Kody błędów

HTTP	`error`	Ponawiać?	Uwagi
400	`invalid_request`	Nie	Parametr nie przeszedł walidacji — popraw żądanie.
401	`missing_api_key` / `unknown_api_key`	Nie	Zobacz Uwierzytelnianie.
403	`inactive_api_key` / `account_blocked`	Nie	Klucz wyłączony lub konto zawieszone.
402	`insufficient_credits`	Nie	Doładuj. Treść zawiera `required` i `balance`.
429	`rate_limited`	Tak, po `retry_after_ms`	Przekroczono limit na minutę.
409	`request_in_progress`	Tak	Identyczne idempotentne żądanie wciąż jest w toku.
422	(konflikt idempotency)	Nie	`Idempotency-Key` użyto ponownie z inną treścią.
503	`service_temporarily_unavailable` / `too_many_concurrent_requests`	Tak, z odczekaniem	Przejściowy limit przepustowości.
504	`result_timeout`	Tak	Pobranie z serwera nadrzędnego przekroczyło `deadline_ms`.

Ponawiaj 429 / 503 / 504 / 409 z wykładniczym odczekiwaniem. Gdy obecne jest retry_after_ms, odczekaj co najmniej tyle czasu przed ponowieniem.
Nigdy nie ponawiaj 400 / 401 / 402 / 403 — żądanie się nie powiedzie, dopóki go nie zmienisz.
Oficjalne SDK ponawiają już za Ciebie błędy przejściowe (domyślnie 2 ponowienia) i udostępniają flagę retryable na błędzie.