Начало работыОшибки

Ошибки

Ошибки возвращаются в виде JSON со статусом 4xx или 5xx. Формат соответствует протоколу эндпоинта, поэтому OpenAI SDK и Anthropic SDK выбрасывают свои обычные классы исключений. Есть одно исключение: если непотоковый запрос выполняется уже 90 секунд, последующая ошибка приходит в теле ответа со статусом 200 (см. Долгие запросы).

Коды ошибок

КодСтатусКогда возникает
invalid_api_key401API-ключ отсутствует, имеет неверный формат, неизвестен, отозван или истёк. В сообщении об истёкшем ключе указана дата окончания его срока действия.
account_suspended403Аккаунт приостановлен. Все его ключи отклоняются, пока приостановка не будет снята; обратитесь в поддержку.
account_banned403Аккаунт заблокирован. Его ключи отозваны, а остаток средств на балансе аннулирован.
card_network_blocked403Пополнение картой отклонено: запрос пришёл через VPN, Tor или из сети дата-центра.
card_account_risk403Пополнение картой отклонено: система Stripe по борьбе с мошенничеством присвоила аккаунту наивысший уровень риска, поэтому пополнять его баланс картой нельзя. Пополнение криптовалютой по-прежнему доступно.
model_not_found404ID в model не соответствует ни одной включённой модели. Список ID можно получить через GET /v1/models.
unsupported_content400Запрос содержит часть, которую модель не принимает: изображение или видео для модели, в чьих input_modalities их нет; видео, переданное не как URL https:// (в том числе видео в base64), или URL изображения, который не начинается с https://, http:// или data:; либо аудио или файл, которые не принимает ни одна модель.
content_policy_violation400Запрос заблокирован автоматической проверкой безопасности.
stateless_only400В запросе к /v1/responses задан previous_response_id или background: true. Вместо этого отправляйте всю переписку в input, без background.
invalid_request400Тело запроса не прошло проверку (например, нет max_tokens в запросе к /v1/messages; n не равно 1; больше 4 промптов в массиве prompt для /v1/completions; service_tier: "priority" у модели без приоритетного уровня; тип инструмента, отличный от function (или от custom и namespace на /v1/responses); либо /v1/completions с моделью, у которой нет эндпоинта completions), тело не получено вовремя (статус 408) или больше 16 MiB (статус 413), либо модель отклонила запрос, например из-за промпта длиннее контекстного окна или большего числа изображений, чем она принимает. При отклонении моделью сохраняются её собственные статус 4xx и сообщение.
insufficient_balance402Баланса не хватает, чтобы покрыть оценку входных токенов и бюджет вывода не менее 256 токенов. Пополните баланс.
key_spend_cap_reached402Сумма, резервируемая под этот запрос, вместе со списанными средствами ключа и резервами его других выполняющихся запросов превысила бы дневной, месячный или общий лимит расходов ключа.
rate_limit_exceeded429Слишком много запросов за эту минуту для ключа или аккаунта, слишком много параллельных запросов для аккаунта, слишком большая доля бюджета на тела выполняющихся запросов занята крупными загрузками аккаунта или — для пробного аккаунта — в течение часа запросы из одной сети отправляют более 2 пробных аккаунтов. Поминутные лимиты и лимит пробных аккаунтов на сеть возвращают Retry-After.
capacity_exhausted429Все реплики модели оставались заняты в течение 30 секунд повторных попыток (у пробных аккаунтов повторных попыток нет, и запрос сразу завершается ошибкой), либо шлюз ненадолго перегружен или перезапускается (статус 503). Подождите столько секунд, сколько указано в Retry-After. Если у модели вообще нет мощностей для обслуживания, вместо этого возвращается model_unavailable. Плата не взимается.
model_unavailable503У модели сейчас нет мощностей для обслуживания, например пока заменяются её GPU. Запрос сразу завершается ошибкой — для всех аккаунтов и без повторных попыток. Retry-After указывает, через сколько секунд мы снова проверим модель; повторите запрос тогда или используйте другую модель. Плата не взимается.
safety_unavailable503Проверка безопасности превысила время ожидания или завершилась ошибкой, поэтому запрос отклонён, а не отправлен без проверки. Повторите попытку чуть позже.
card_network_check_unavailable503Пополнение картой отклонено, потому что проверка сети временно недоступна; повторите попытку или оплатите криптовалютой.
upstream_error502Произошёл сбой бэкенда модели, либо запрос был остановлен по 10-минутному лимиту времени, через 2 минуты без вывода от модели или из-за перезапуска. Непредвиденная внутренняя ошибка возвращает этот код со статусом 500, кратковременный сбой или перезапуск на нашей стороне — со статусом 503 и Retry-After, а сбой бэкенда — со статусом 502, в каждом случае до отправки ответа. Лимиты времени срабатывают позже: они прерывают поток, а непотоковый ответ, который выполняется дольше 90 секунд, к этому моменту уже отправлен со статусом 200, поэтому эта ошибка — из-за лимита времени или по любой другой причине — приходит в его теле без Retry-After (см. «Долгие запросы»). Если модель ещё ничего не сгенерировала, плата не взимается; повторите запрос. Если вывод уже сгенерирован, оплачиваются оценка входных токенов и вывод, сгенерированный до сбоя или остановки. Клиент, который отключается, никогда не получает эту ошибку; с него взимается плата за оценку входных токенов, даже если вывод не был сгенерирован.

Что именно блокирует content_policy_violation, определено в правилах допустимого использования.

Формат OpenAI

Используется в /v1/chat/completions, /v1/responses, /v1/models и /v1/balance. Поле code содержит один из кодов выше. Пример:

json
{
  "error": {
    "type": "rate_limit_error",
    "code": "capacity_exhausted",
    "message": "All model replicas are busy. Retry shortly."
  }
}

Формат Anthropic

Используется в /v1/messages. В этом формате нет поля code, поэтому смотрите на HTTP-статус и error.type. Пример:

json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens is required."
  }
}

Типы ошибок по статусам

СтатусOpenAI error.typeAnthropic error.type
400invalid_request_errorinvalid_request_error
401authentication_errorauthentication_error
402insufficient_quotabilling_error
403permission_errorpermission_error
404not_found_errornot_found_error
408invalid_request_errorinvalid_request_error
413invalid_request_errorrequest_too_large
429rate_limit_errorrate_limit_error
500, 502, 503api_errorapi_error

Заголовки

  • x-request-id есть в каждом ответе, включая ошибки. Указывайте его, когда обращаетесь в поддержку.
  • Retry-After (в секундах) приходит с capacity_exhausted, с model_unavailable (секунды до следующей проверки модели, не больше 15), с поминутным и сетевым пробным rate_limit_exceeded, а также с 503 upstream_error (кратковременный сбой или перезапуск на нашей стороне).

Когда повторять запрос

ОшибкаЧто делать
capacity_exhaustedПодождите Retry-After секунд и повторите запрос. Статус 429 означает, что платные запросы уже повторялись в течение не более чем 30 секунд; статус 503 означает, что шлюз был перегружен или перезапускался и запрос так и не дошёл до модели.
model_unavailableПодождите Retry-After секунд и повторите запрос: именно тогда мы снова проверим модель. Запрос завершился сразу, без повторов, потому что у модели не было мощностей для обработки. Такой сбой может длиться несколько минут, поэтому, если ошибка не проходит, переключитесь на другую модель.
rate_limit_exceededПри поминутном лимите подождите Retry-After секунд. При лимите параллельных запросов повторите запрос, когда завершится один из выполняющихся. При лимите пробных аккаунтов на сеть подождите Retry-After секунд или пополните баланс: на платные аккаунты этот лимит не распространяется.
safety_unavailableПовторите запрос через несколько секунд. Проверка безопасности работает по принципу fail-closed: если её не удаётся выполнить, запрос отклоняется, а не передаётся дальше без проверки.
upstream_errorПри статусе 503 подождите Retry-After секунд и повторите запрос. В остальных случаях, в том числе в теле ответа со статусом 200, повторяйте с экспоненциальной задержкой.
insufficient_balance, key_spend_cap_reachedПополните баланс, повысьте лимит или дождитесь его сброса. Повторять запрос раньше бесполезно.
Другие 4xxИсправьте запрос. Повтор без изменений вернёт ту же ошибку.

Неудачные запросы, которые не сгенерировали вывода, не оплачиваются, в том числе запросы, остановленные по лимиту времени или из-за перезапуска. Единственное исключение — отключение вашего клиента: в этом случае оценка входных токенов оплачивается, даже если вывода не было. Если запрос завершается ошибкой или останавливается после того, как модель что-то сгенерировала, оплачивается оценка входных токенов плюс вывод, сгенерированный до остановки. См. как тарифицируется запрос.

Долгие запросы

Непотоковый ответ — это один JSON-объект, готовый, когда модель заканчивает генерацию. Если он готов в течение 90 секунд после поступления запроса, он отправляется как обычно: результат или ошибка со своим статусом и заголовками.

Если ответ не готов через 90 секунд, его отправка начинается в этот момент, чтобы соединение оставалось открытым: отправляются статус 200 и Content-Type: application/json (вместе с x-request-id), а тело начинается с символа новой строки (\n), за которым каждые 15 секунд следует ещё один. Когда результат готов, следом идёт JSON-объект, и ответ завершается. JSON-парсеры пропускают пробельные символы перед значением, поэтому OpenAI SDK и Anthropic SDK, JSON.parse, json.loads и response.json() читают такой ответ без изменений. Так непотоковый запрос получает весь лимит времени в 10 минут.

Когда статус 200 уже отправлен, ошибка не может его изменить. Ошибка после этого момента (лимит времени в 10 минут, 2 минуты без вывода от модели, сбой бэкенда или перезапуск) приходит в теле ответа со статусом 200 в виде обычного объекта ошибки: в формате OpenAI или, на /v1/messages, в формате Anthropic. Заголовок Retry-After с ней отправить невозможно. Клиент, который проверяет только статус, ошибку не заметит, поэтому проверяйте, есть ли в теле поле error верхнего уровня. Тарификация такая же, как у любого другого неудачного или остановленного запроса (см. выше), а закрытие соединения во время ожидания считается отключением клиента.

Потоковая передача с "stream": true по-прежнему хороший выбор для длинных генераций: первые токены видны сразу, а вывод поступает по мере генерации. Но чтобы избежать тайм-аута, она не нужна.