Ошибки и повторы

Ошибки возвращаются как JSON со стабильным, машиночитаемым кодом error и соответствующим HTTP-статусом.

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

Коды ошибок

HTTP	`error`	Повторять?	Примечания
400	`invalid_request`	Нет	Параметр не прошёл валидацию — исправьте запрос.
401	`missing_api_key` / `unknown_api_key`	Нет	См. Аутентификация.
403	`inactive_api_key` / `account_blocked`	Нет	Ключ отключён или аккаунт приостановлен.
402	`insufficient_credits`	Нет	Пополните счёт. Тело включает `required` и `balance`.
429	`rate_limited`	Да, после `retry_after_ms`	Вы превысили лимит в минуту.
409	`request_in_progress`	Да	Идентичный идемпотентный запрос ещё выполняется.
422	(конфликт идемпотентности)	Нет	`Idempotency-Key` был повторно использован с другим телом.
503	`service_temporarily_unavailable` / `too_many_concurrent_requests`	Да, с задержкой	Временный лимит ёмкости.
504	`result_timeout`	Да	Восходящая выборка превысила `deadline_ms`.

Повторяйте 429 / 503 / 504 / 409 с экспоненциальной задержкой. Когда присутствует retry_after_ms, ждите как минимум столько времени перед повтором.
Никогда не повторяйте 400 / 401 / 402 / 403 — запрос не пройдёт, пока вы его не измените.
Официальные SDK уже повторяют временные ошибки за вас (по умолчанию 2 повтора) и предоставляют флаг retryable на объекте ошибки.