# Ошибки

> Конверты ошибок OpenAI и Anthropic, коды и что с ними делать, какие запросы повторять.

Ошибка приходит в конверте того формата, на который вы отправили запрос, —
так её понимает ваш SDK. `request_id` указывайте при обращении в поддержку;
он же приходит в заголовке `x-request-id` каждого ответа.

Все эндпоинты, кроме `/v1/messages`, — конверт OpenAI:

```json
{"error": {"message": "...", "type": "...", "code": "...", "param": "...", "request_id": "req_..."}}
```

`/v1/messages` — конверт Anthropic; наши `code` и `param` лежат внутри `error`
дополнительными полями, а `request_id` — на верхнем уровне:

```json
{"type": "error", "error": {"type": "not_found_error", "message": "...", "code": "model_not_found"}, "request_id": "req_..."}
```

Поле `param` есть, только когда ошибка относится к конкретному параметру.
`error.type` в конверте Anthropic зависит только от HTTP-статуса:
400 — `invalid_request_error`, 401 — `authentication_error`,
402 — `billing_error`, 403 — `permission_error`, 404 — `not_found_error`,
413 — `request_too_large`, 429 — `rate_limit_error`, 500 и 502 — `api_error`,
503 — `overloaded_error`.

## Коды ошибок

| HTTP | code | Что это значит |
| --- | --- | --- |
| 400 | `invalid_request` | Некорректное тело запроса (нет `model`, битый JSON) — проверьте параметры. С этим же кодом приходит отказ провайдера, причину которого шлюз не распознал; тогда HTTP-статус — статус провайдера (4xx). |
| 400 | `unsupported_parameter` | Параметр запроса не поддерживается — его имя в поле param. Уберите его и повторите. См. [Параметры запроса](https://ai-seller.vibe-codes.ru/docs/params). |
| 400 | `unsupported_value`, `invalid_value` | Провайдер модели отклонил значение параметра; имя параметра — в поле param, если его удалось определить. |
| 400 | `context_length_exceeded` | Запрос не помещается в контекстное окно модели. Сообщение начинается с «Prompt is too long:» — Claude Code по нему запускает сжатие контекста. |
| 400 | `content_policy_violation` | Запрос отклонён политикой контента модели — измените промпт. |
| 400 | `invalid_image` | Модель отклонила референсное изображение — попробуйте другое. |
| 401 | `invalid_api_key` | Ключ не передан, не найден или отозван — проверьте заголовок Authorization. |
| 402 | `insufficient_quota` | Баланс исчерпан — пополните счёт. Если остаток занят запросами в работе, повторите после их завершения. |
| 403 | `spend_limit_exceeded` | Достигнут лимит трат этого ключа — поднимите лимит или создайте новый ключ. |
| 404 | `model_not_found` | Модель не существует, выключена, недоступна вашему аккаунту или не подходит к эндпоинту (модель картинок на чате) — сверьтесь с GET /v1/models с вашим ключом. |
| 404 | `not_found` | Неизвестный эндпоинт, видео-задача не найдена или видео ещё не готово. |
| 413 | `invalid_request` | Тело запроса больше лимита — см. [Лимиты](https://ai-seller.vibe-codes.ru/docs/limits). |
| 422 | `generation_failed` | Модель не вернула изображение. Повторите запрос или переформулируйте промпт. |
| 429 | `rate_limit_exceeded` | Слишком много одновременных запросов аккаунта или модель сейчас перегружена у провайдера. Повторите после паузы из заголовка `Retry-After`. |
| 500 | — | Внутренняя ошибка шлюза (`type: server_error`, без `code`). Повторите запрос; если повторяется — напишите в поддержку с `request_id`. |
| 502 | `upstream_unavailable` | Провайдеры модели временно недоступны — повторите запрос позже. |
| 503 | `service_unavailable` | Сервис на обслуживании или временно недоступен — повторите позже. |
| 503 | — | Модель временно без доступных маршрутов (`type: server_error`, без `code`) — повторите позже или выберите другую модель. |

## Повторы

Повторять имеет смысл запросы с кодами 429, 500, 502, 503 и 422. Остальные
ошибки повтором не лечатся — сначала исправьте запрос, ключ или баланс.

- При `429` выдерживайте паузу из заголовка `Retry-After`; если его нет —
  экспоненциальный бэкофф (1, 2, 4… секунды). OpenAI и Anthropic SDK делают это
  сами.
- Ошибка, пришедшая событием посреди потока, — тоже повод повторить запрос
  целиком (см. [Стриминг](https://ai-seller.vibe-codes.ru/docs/streaming)).

> Не получается разобраться? Напишите на support@example.com и приложите `request_id`
> из ответа.