Ошибки API

На этой странице представлен справочник по всем кодам ошибок API взаимодействия, описан формат ответа об ошибке и объяснено, как API обрабатывает ошибки для различных типов запросов.

Стандартные коды ошибок API

Эти общие коды ошибок на уровне запроса соответствуют стандартным кодам состояния HTTP. Используйте поле code в логике вашего приложения для программной обработки ошибок.

Код Статус HTTP Описание Рекомендуемые действия
invalid_request 400 Неверный запрос Запрос имеет некорректный формат или содержит недопустимые параметры. Проверьте введенные данные, сверившись с API-справочником .
parameter_unknown 400 Неверный запрос Запрос содержит неизвестный параметр. Удалите неопознанный параметр и повторите попытку.
authentication 401 Несанкционированный доступ Отсутствует или недействителен ключ API. Подтвердите свой API-ключ .
permission_denied 403 Запрещено Ваш API-ключ не предоставляет доступ к этому ресурсу. Проверьте права доступа к вашему API-ключу и доступ к проекту.
not_found 404 Не найдено Запрошенный ресурс не найден. Проверьте путь к ресурсу и его параметры.
model_not_found 404 Не найдено Указанная модель не найдена. Проверьте название модели или воспользуйтесь другой моделью в качестве запасного варианта.
rate_limit_exceeded 429 Слишком много запросов Вы превысили лимит запросов или токенов в минуту или в секунду. Подождите и повторите попытку с экспоненциальной задержкой.
quota_exceeded 429 Слишком много запросов Вы превысили свою суточную норму. Дождитесь сброса квоты или запросите её увеличение.
cancelled 499 Клиент закрыл запрос Клиент отменил запрос до его завершения. Никаких действий не требуется. Обычно это означает, что клиент отключился.
api_error Ошибка 500 (внутренняя ошибка сервера) На сервере произошла непредвиденная ошибка. Повторите запрос. Если проблема не исчезнет, ​​обратитесь в службу поддержки.
service_unavailable Сервис 503 недоступен Сервис временно перегружен или недоступен. Подождите и повторите попытку с экспоненциальной задержкой.

Коды блокировки генерации

Эти коды ошибок указывают на то, что ограничения, связанные с политикой, безопасностью или контентом, заблокировали вывод модели. При получении одного из таких кодов измените входные данные и повторите попытку.

Код Описание
safety Нарушения правил безопасности (вредоносный контент) заблокировали запрос.
recitation Запрос был заблокирован из-за ограничений, связанных с авторскими правами или правилами цитирования.
language Запрос был заблокирован из-за неподдерживаемого языка.
prohibited_content Запрос был заблокирован в соответствии с правилами размещения запрещенного контента.
spii Ограничения, связанные с конфиденциальной личной информацией, заблокировали запрос.
blocklist Запрещенные термины, внесенные в черный список, заблокировали запрос.
image_safety Нарушения правил техники безопасности препятствовали генерации изображений.
image_prohibited_content Правила размещения запрещенного контента блокировали генерацию изображений.
image_recitation Ограничения, связанные с авторскими правами или правилами цитирования, препятствовали созданию изображений.
image_other Неуказанные причины заблокировали генерацию изображения.
content_blocked Запрос был заблокирован по неуказанной причине, связанной с политикой компании.

Коды ошибок генерации

Эти коды ошибок указывают на структурную проблему в выходных данных, сгенерированных моделью (например, некорректный вызов функции или необъявленный вызов инструмента).

Код Описание
malformed_function_call Модель выдала вызов функции, который не удалось проанализировать.
malformed_tool_call Модель выдала запрос на использование инструмента, который не удалось обработать.
unexpected_tool_call В модели был вызван инструмент, который не был указан в запросе.
no_image Модель не смогла сгенерировать изображение.
too_many_tool_calls Модель сгенерировала больше вызовов инструментов, чем было разрешено.
missing_thought_signature В ответе отсутствует необходимая сигнатура мысли.

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

Все ошибки, возникающие при использовании API взаимодействий, возвращают объект error , содержащий code и message . Например, передача неподдерживаемого типа инструмента возвращает:

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'. Supported values: 'function', 'code_execution', 'mcp_server', 'filesystem', 'google_maps', 'google_search', 'bash', 'computer_use', 'file_search', 'url_context'."
  }
}
Поле Тип Описание
code нить Машинночитаемый код ошибки в snake_case .
message нить Удобочитаемое описание того, что пошло не так.

Как доставляются ошибки

API обрабатывает ошибки по-разному в зависимости от того, отправляете ли вы стандартный HTTP-запрос или потоковый (SSE) запрос.

Стандартные HTTP-запросы

Для стандартных (не потоковых) запросов API устанавливает код состояния HTTP-ответа (например, 400 Bad Request , 401 Unauthorized или 429 Too Many Requests ) и возвращает объект error в теле JSON-ответа:

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'."
  }
}

Запросы потоковой передачи (SSE)

Для потоковых запросов ( stream: true ) API отправляет события ошибок через поток Server-Sent Events (SSE) с event_type , установленным в значение "error" . Поле error содержит тот же code и структуру message :

{
  "event_type": "error",
  "error": {
    "code": "not_found",
    "message": "Failed to get completed interaction: Result not found."
  }
}

Полную схему событий SSE см. в справочнике API взаимодействий .

Что дальше?