Ошибки приходят с обычным HTTP-статусом и телом в формате OpenAI API — тем же, что ожидают совместимые SDK.
json
{
"error": {
"message": "Описание ошибки человеку",
"type": "invalid_request_error",
"code": "model_not_found"
}
}OpenAI-совместимые SDK сами разбирают это тело и кидают исключение — смотрите статус и error.message.
| Статус | Что значит | Что делать |
|---|---|---|
400 | Bad Request — некорректное тело запроса: битый JSON, нет обязательного поля, недопустимое значение параметра. | Проверьте JSON и параметры (model, messages). Текст в error.message подскажет, что именно не так. |
401 | Unauthorized — ключ не передан, неверный или отозван. | Проверьте заголовок Authorization: Bearer cai-.... Если ключ отзывали — создайте новый в разделе API-ключи. |
402 | Payment Required — на балансе недостаточно средств для запроса. | Пополните баланс. Сколько стоит запрос — см. Тарификация. |
403 | Forbidden — доступ к этому ресурсу или модели для вашего ключа закрыт. | Убедитесь, что модель есть в каталоге и доступна (status — не «скоро»). |
404 | Not Found — неизвестная модель или несуществующий путь. | Проверьте имя модели (поле model) и путь эндпоинта — /v1/chat/completions, /v1/embeddings и т. д. |
408 / 504 | Timeout — провайдер слишком долго не отвечал. | Повторите запрос. Для длинных ответов используйте стриминг (stream: true) — так соединение не «висит» в ожидании всего ответа сразу. |
429 | Too Many Requests — превышен лимит частоты запросов. | Повторите с экспоненциальной задержкой (0.5 с, 1 с, 2 с …). Если есть заголовок Retry-After — подождите указанное в нём время. |
500 | Internal Server Error — внутренняя ошибка шлюза. | Повторите запрос. Если воспроизводится стабильно — сообщите нам, приложив время и модель (ключ не нужен). |
502 / 503 | Провайдер модели временно недоступен или перегружен. | Повторите с задержкой или временно переключитесь на другую модель из каталога. |
Безопасно повторять запрос имеет смысл на 408, 429, 500, 502, 503, 504 — с экспоненциально растущей задержкой и небольшим случайным разбросом (jitter), 3–5 попыток. На 400, 401, 402, 403, 404 повторять бессмысленно — это ошибки запроса или аккаунта, их нужно чинить, а не ретраить. Официальные OpenAI- и Anthropic-SDK уже делают такие ретраи сами — отдельно ничего писать не нужно.
Дальше: OpenAI-совместимый API · FAQ для разработчиков · API-ключи.