Ошибки API
Структура ошибок, HTTP-статусы и действия клиента
Проверяйте HTTP-статус, тип содержимого и объект error до чтения результата модели
Формат ошибки
{
"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: в сообщении может отсутствовать
Не привязывайте обработчик к полному тексту с конкретным идентификатором
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
Потоковые ответы
До начала SSE ошибка может прийти как обычный JSON Во время потока обрабатывайте события ошибки и разрыв соединения Неполный поток не является успешно завершённым ответом
Ответ без текста
HTTP 200 не гарантирует непустой текст
Вызов инструмента, отказ модели, рассуждения и достижение лимита обрабатываются по структуре ответа
Не классифицируйте каждый пустой content как технический сбой
Обращение в поддержку
Сохраните время UTC, HTTP-метод, путь, модель, статус и идентификатор запроса, если он доступен Удалите API-ключ и пользовательские секреты перед отправкой данных