Коды ошибок
Все ошибки — в OpenAI-совместимом формате:
{
"error": {
"message": "человекочитаемое описание",
"type": "invalid_request_error",
"code": "invalid_request"
}
}Таблица кодов
| HTTP | type | code | Когда возникает | Что делать |
|---|---|---|---|---|
| 400 | invalid_request_error | invalid_request | Тело не прошло валидацию (нет model, пустой messages, неверный image_url и т.п.) | Проверить тело запроса по описанию эндпоинта |
| 400 | invalid_request_error | invalid_request | Апстрим отклонил запрос как некорректный (проброс от провайдера) | Проверить параметры, специфичные для модели/провайдера |
| 401 | authentication_error | invalid_api_key | Ключ отсутствует, не начинается с sk-tn-, отозван или аккаунт заблокирован | Проверить заголовок Authorization, при необходимости выпустить новый ключ |
| 402 | insufficient_quota | insufficient_quota | Баланс аккаунта ≤ 0 | Пополните баланс в кабинете — карта/СБП или счёт для юрлица, см. «Оплата и счета» |
| 404 | invalid_request_error | model_not_found | model не существует или отключена в каталоге | Свериться со списком моделей |
| 404 | invalid_request_error | not_found | Запрошен несуществующий путь/метод | Проверить URL — актуальные эндпоинты перечислены в этой документации |
| 429 | rate_limit_error | rate_limit_exceeded | Превышен rate limit ключа (см. «Аутентификация») | Повторить с задержкой — приходит заголовок Retry-After |
| 502 | api_error | upstream_unavailable | Апстрим-провайдер недоступен, а фолбэк на альтернативный маршрут не сработал | Повторить запрос позже; при системной проблеме — написать в поддержку |
| 500 | api_error | null | Непредвиденная внутренняя ошибка шлюза | Написать в поддержку с точным временем запроса и телом ответа — requestId в ответе клиенту не передаётся, это внутренний идентификатор для логов |
Примеры
Недостаточно средств:
{
"error": {
"message": "Insufficient balance. Top up your account in the dashboard.",
"type": "insufficient_quota",
"code": "insufficient_quota"
}
}Неизвестная модель:
{
"error": {
"message": "Model 'gpt-5-mega' not found",
"type": "invalid_request_error",
"code": "model_not_found"
}
}Невалидный ключ:
{
"error": {
"message": "Invalid API key",
"type": "authentication_error",
"code": "invalid_api_key"
}
}Что не тарифицируется
Запрос, завершившийся ошибкой (400/401/402/404/429/502/500),
никогда не списывает баланс — тарифицируются только успешно
завершённые запросы (или прерванный стрим, если апстрим уже успел
отдать часть контента, см. «Chat Completions»).