Ошибки API

Структура ошибок, HTTP-статусы и действия клиента

Проверяйте HTTP-статус, тип содержимого и объект error до чтения результата модели

Формат ошибки

json

{
  "error": {
    "code": "",
    "message": "Invalid token (request id: example)"
  }
}

Поле	Тип	Описание
`error.message`	string	Сообщение о причине
`error.code`	string, number или null	Код ошибки, может быть пустым
`error.type`	string	Дополнительный тип, если присутствует
`error.param`	string или null	Параметр, если указан

Состав полей зависит от источника ошибки Строка request id: в сообщении может отсутствовать Не привязывайте обработчик к полному тексту с конкретным идентификатором

Ошибки OpenRouter и расчёта

Код или сообщение	Как разбирать
`model_price_error`, `no available endpoints`	Для модели нет доступных upstream endpoints
`model_price_error`, `no compatible priced endpoint`	Нет подходящего исполнителя с ценой при заданных ограничениях провайдера и параметров
`model_price_error`, сообщение о `configured_price` или резерве	Метод не смог определить цену или резерв, одного изменения текста запроса недостаточно
`invalid_batch_price`	Не удалось определить цену batch-варианта, читайте вложенное сообщение
`upstream_error`	Ошибка OpenRouter или исполнителя, дополнительные сведения могут находиться в `metadata`

model_price_error не всегда означает отсутствие тарифа у модели. Проверьте полный текст ошибки, модель, метод и объект provider

При 429 смотрите источник ограничения, например metadata.provider_name и metadata.limit_source, если они присутствуют. Статус сам по себе не определяет, кто ограничил запрос

HTTP-статусы

Статус	Возможная причина	Действие
400	Некорректный JSON, пропущенное поле, недопустимый параметр или данные	Исправить запрос
401	Ключ отсутствует или не принят	Проверить авторизацию
403	Запрет доступа или неподходящий класс модели	Проверить права, модель и метод
404	Неизвестный путь, метод или ресурс	Проверить URL и HTTP-метод
429	Ограничение частоты или квоты, если возвращено сервисом или поставщиком	Уменьшить нагрузку, учитывать Retry-After при наличии
503 с `model_not_found`	Модель не найдена или недоступна для такого вызова	Сверить идентификатор с каталогом
Другие 5xx	Возможный временный сбой сервиса или поставщика	Оценить безопасный ограниченный повтор

Код 503 сам по себе не определяет стратегию повтора

Типичные ошибки запроса

Сообщение	Причина
`field messages is required`	Отсутствует messages
`Model name not specified, model name cannot be empty`	Не передан model
`You are not allowed to sample from this model`	Модель не подходит для метода генерации
`max_tokens must be greater than thinking.budget_tokens`	Общий лимит не превышает бюджет рассуждений
`Could not process image`	Невозможно обработать изображение
`Invalid Responses API request`	Некорректный запрос Responses или неподдерживаемое продолжение

Ошибка без JSON

Неизвестный путь или промежуточный сервер может вернуть HTML или текст Сохраняйте HTTP-статус и ограниченный безопасный фрагмент ответа Не заменяйте исходную ошибку исключением парсера JSON

Ошибка внутри HTTP 200

В Chat Completions ошибка может находиться в choices[].error, а finish_reason иметь значение error, даже если message.content содержит часть ответа Проверяйте эти поля до использования результата, HTTP-статус и непустой текст сами по себе не подтверждают завершение генерации

Потоковые ответы

До начала SSE ошибка может прийти как обычный JSON Во время потока обрабатывайте события ошибки и разрыв соединения Не считайте неполный поток успешно завершённым ответом

Ответ без текста

HTTP 200 не гарантирует непустой текст Вызов инструмента, отказ модели, рассуждения и достижение лимита обрабатываются по структуре ответа Не классифицируйте каждый пустой content как технический сбой

Обращение в поддержку

Сохраните время UTC, HTTP-метод, путь, модель, статус и идентификатор запроса, если он доступен Удалите API-ключ и пользовательские секреты перед отправкой данных

Повторы, журнал и поддержка

← Идентификаторы моделей

Лимиты и повторные запросы →