Коды ошибок и устранение неполадок

Определите, что именно завершилось ошибкой

1. Запишите фактический статус HTTP, метод и путь запроса. Статус HTTP и код ошибки приложения описывают разные уровни; не подменяйте одно другим.
2. Читайте поля ошибки в соответствии с протоколом вызова. Ответы нативного API, OpenAI, Claude и Gemini имеют разную структуру.
3. При потоковой передаче проверяйте также события ошибок и состояние завершения, а для асинхронных заданий — status. HTTP 200 не гарантирует успешную генерацию.
4. Используйте таблицу ниже, чтобы исправить запрос или оценить необходимость повтора. message — поясняющий текст, а не стабильное значение перечисления; не стройте ветвление по формулировке сообщения.

Перечисление кодов ошибок платформы

Это полное перечисление кодов ошибок приложения платформы. Имена служат справочными метками; значения code в ответах являются числами. Распространённый статус HTTP приведён для диагностики, а не как фиксированное соответствие для каждого эндпоинта. Используйте фактический статус HTTP и тело ответа. Переданный без преобразования code вышестоящего провайдера может не входить в это перечисление.

Один лишь HTTP 429 не позволяет надёжно различить ограничение частоты и параллелизма. Различайте их только при наличии явного числового кода ошибки. Проверяйте идентификаторы моделей в списке моделей; не изменяйте значения model самостоятельно.

Чтение ошибок по протоколам

Примеры ниже показывают распространённые структуры, формируемые платформой, а не единый формат, гарантированный для любой ошибки. Ошибки аутентификации могут возникать на разных уровнях обработки; передаваемые ответы вышестоящего провайдера могут сохранять собственную структуру, строковые коды или типы. Перед разбором определите фактическую структуру. Если она неизвестна, сохраните исходные поля и статус HTTP вместо принудительного преобразования.

Нативные API платформы

Обычно следует читать error.code и error.message. Поле requestId может отсутствовать.

{
  "success": false,
  "error": {
    "code": 10000,
    "message": "Bad request"
  },
  "requestId": "req_example"
}

Некоторые ошибки используют поля верхнего уровня code и message. Клиенты должны допускать это и не считать отсутствие объекта error доказательством успеха. Ответы проверки параметров также могут не содержать числового кода ошибки. Считайте отсутствующий код неизвестным, а не придумывайте его.

API, совместимые с OpenAI

Распространённые ошибки платформы используют поля верхнего уровня code, message и type; они не обязательно вложены в error.

{
  "code": 40000,
  "message": "Insufficient credit",
  "type": "api_error"
}

type — категория протокола, а code в этой структуре — числовой код ошибки платформы. Одного api_error недостаточно для решения о повторной попытке. Переданные ошибки провайдера и ошибки потока могут содержать вложенный error; обрабатывайте фактический ответ протокола. См. Chat Completions и Responses.

API, совместимые с Claude

В распространённой структуре верхний type равен error, конкретная категория находится в error.type, а описание — в error.message. Эта структура не содержит числового code платформы. Не придумывайте его.

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens must be a positive safe integer"
  }
}

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

См. сообщения Claude.

Ошибки в формате Gemini

В ответе формата Gemini читайте error.code, error.message и error.status. Здесь status — строковая категория, а не статус HTTP или состояние асинхронного задания.

{
  "error": {
    "code": 10000,
    "message": "Bad request",
    "status": "INVALID_ARGUMENT"
  }
}

Ошибки, сформированные платформой в этой структуре, используют числовые значения платформы в code. Локальное соответствие строкового status приведено ниже; оно не перечисляет все статусы вышестоящего провайдера.

503 имеет приоритет и использует UNAVAILABLE, а не INTERNAL. Ответы вышестоящего провайдера могут придавать code и status другой смысл. Не применяйте таблицу ошибок платформы к каждому числовому коду Gemini.

Безопасные повторные попытки

Если присутствует корректный заголовок Retry-After, соблюдайте его. Не предполагайте, что он есть у каждой ошибки. Автоматический повтор неидемпотентного запроса генерации может выполнить его ещё раз и привести к дополнительной оплате. Эта страница не обещает общей поддержки ключей идемпотентности; самостоятельно добавленный Idempotency-Key не гарантирует устранение дублей.

Если вы уже получили jobId, запросите это задание, прежде чем создавать новое. Если jobId отсутствует, а результат неизвестен, сохраните идентификатор запроса и временную метку для расследования.

Потоки и асинхронные задания

Запросы SSE

После начала SSE статус HTTP может оставаться 200, а более поздняя ошибка может передаваться событием или полезной нагрузкой внутри потока. Разбирайте события и данные выбранного протокола и проверяйте нормальное завершение. При ошибке или неожиданном обрыве не считайте частичный текст или изображение полностью успешным результатом. Имена событий и полезная нагрузка различаются по эндпоинтам. Не проверяйте только одно фиксированное поле error и не считайте получение какого-либо текста признаком успеха.

Асинхронные задания

Ответ создания с data.jobId означает принятие, а не завершение генерации. Успешный HTTP-ответ при опросе задания означает успешный запрос состояния. Всё равно необходимо проверить data.status задания:

• PENDING, CONNECT, PROCESSING: продолжайте опрос согласно документации Jobs.
• COMPLETED: прочитайте outputResult.
• FAILED, CANCELLED: прекратите опрос и сохраните идентификатор задания и очищенные от конфиденциальных данных сведения ответа для расследования.

Подробности ошибки могут находиться в data.outputResult.error. Поле необязательно и не гарантировано для каждого неудачного задания. Используйте Jobs только тогда, когда ответ создания явно возвращает jobId. Не применяйте опрос заданий к эндпоинтам, возвращающим результат напрямую через JSON или SSE.

Диагностика для пользователей и ИИ-ассистентов

Передавайте поддержке или ИИ-ассистенту следующие сведения, очищенные от конфиденциальных данных. Для отсутствующих полей используйте unknown; если HTTP-ответ не получен, статус HTTP также укажите как unknown. Сохраняйте пути полей и исходные типы значений, например error.code: 10000 (number) или error.code: "invalid_api_key" (string). Не преобразуйте строковый code автоматически в числовой код платформы и не придумывайте отсутствующие поля на основе message, статуса HTTP или имён моделей.

time_with_timezone: unknown
method: unknown
path_without_query: unknown
model: unknown
stream: unknown
http_status: unknown
error_code_path_value_and_type: unknown
error_type_path_and_value: unknown
protocol_status_path_and_value: unknown
sanitized_message: unknown
request_id_from_body_or_X-Request-ID: unknown
job_id: unknown
job_status: unknown
retry_after: unknown
retry_count_and_delays: unknown
received_partial_output: unknown

Читайте requestId из тела ответа или заголовка ответа X-Request-ID, если они доступны. Храните jobId как строку, чтобы не потерять точность длинных чисел. Передавайте лишь минимальные параметры запроса, очищенные от конфиденциальных данных. Удаляйте API-ключи, токены, cookies, полные заголовки аутентификации, личные данные, закрытые промпты и содержимое входных файлов. Удаляйте параметры строки запроса URL и входные или выходные URL с подписями либо учётными данными. Не вставляйте полные журналы запросов без проверки.

ИИ-ассистенты должны отличать наблюдаемые поля от возможных причин и указывать недостающие сведения. Недостаток доказательств не должен считаться подтверждением успешности запроса, отсутствия выполнения или отсутствия списания.