Ошибки
Ошибки возвращаются в виде JSON со статусом 4xx или 5xx. Формат соответствует протоколу эндпоинта, поэтому OpenAI SDK и Anthropic SDK выбрасывают свои обычные классы исключений. Есть одно исключение: если непотоковый запрос выполняется уже 90 секунд, последующая ошибка приходит в теле ответа со статусом 200 (см. Долгие запросы).
Коды ошибок
| Код | Статус | Когда возникает |
|---|---|---|
invalid_api_key | 401 | API-ключ отсутствует, имеет неверный формат, неизвестен, отозван или истёк. В сообщении об истёкшем ключе указана дата окончания его срока действия. |
account_suspended | 403 | Аккаунт приостановлен. Все его ключи отклоняются, пока приостановка не будет снята; обратитесь в поддержку. |
account_banned | 403 | Аккаунт заблокирован. Его ключи отозваны, а остаток средств на балансе аннулирован. |
card_network_blocked | 403 | Пополнение картой отклонено: запрос пришёл через VPN, Tor или из сети дата-центра. |
card_account_risk | 403 | Пополнение картой отклонено: система Stripe по борьбе с мошенничеством присвоила аккаунту наивысший уровень риска, поэтому пополнять его баланс картой нельзя. Пополнение криптовалютой по-прежнему доступно. |
model_not_found | 404 | ID в model не соответствует ни одной включённой модели. Список ID можно получить через GET /v1/models. |
unsupported_content | 400 | Запрос содержит часть, которую модель не принимает: изображение или видео для модели, в чьих input_modalities их нет; видео, переданное не как URL https:// (в том числе видео в base64), или URL изображения, который не начинается с https://, http:// или data:; либо аудио или файл, которые не принимает ни одна модель. |
content_policy_violation | 400 | Запрос заблокирован автоматической проверкой безопасности. |
stateless_only | 400 | В запросе к /v1/responses задан previous_response_id или background: true. Вместо этого отправляйте всю переписку в input, без background. |
invalid_request | 400 | Тело запроса не прошло проверку (например, нет 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_balance | 402 | Баланса не хватает, чтобы покрыть оценку входных токенов и бюджет вывода не менее 256 токенов. Пополните баланс. |
key_spend_cap_reached | 402 | Сумма, резервируемая под этот запрос, вместе со списанными средствами ключа и резервами его других выполняющихся запросов превысила бы дневной, месячный или общий лимит расходов ключа. |
rate_limit_exceeded | 429 | Слишком много запросов за эту минуту для ключа или аккаунта, слишком много параллельных запросов для аккаунта, слишком большая доля бюджета на тела выполняющихся запросов занята крупными загрузками аккаунта или — для пробного аккаунта — в течение часа запросы из одной сети отправляют более 2 пробных аккаунтов. Поминутные лимиты и лимит пробных аккаунтов на сеть возвращают Retry-After. |
capacity_exhausted | 429 | Все реплики модели оставались заняты в течение 30 секунд повторных попыток (у пробных аккаунтов повторных попыток нет, и запрос сразу завершается ошибкой), либо шлюз ненадолго перегружен или перезапускается (статус 503). Подождите столько секунд, сколько указано в Retry-After. Если у модели вообще нет мощностей для обслуживания, вместо этого возвращается model_unavailable. Плата не взимается. |
model_unavailable | 503 | У модели сейчас нет мощностей для обслуживания, например пока заменяются её GPU. Запрос сразу завершается ошибкой — для всех аккаунтов и без повторных попыток. Retry-After указывает, через сколько секунд мы снова проверим модель; повторите запрос тогда или используйте другую модель. Плата не взимается. |
safety_unavailable | 503 | Проверка безопасности превысила время ожидания или завершилась ошибкой, поэтому запрос отклонён, а не отправлен без проверки. Повторите попытку чуть позже. |
card_network_check_unavailable | 503 | Пополнение картой отклонено, потому что проверка сети временно недоступна; повторите попытку или оплатите криптовалютой. |
upstream_error | 502 | Произошёл сбой бэкенда модели, либо запрос был остановлен по 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 содержит один из кодов выше. Пример:
{
"error": {
"type": "rate_limit_error",
"code": "capacity_exhausted",
"message": "All model replicas are busy. Retry shortly."
}
}Формат Anthropic
Используется в /v1/messages. В этом формате нет поля code, поэтому смотрите на HTTP-статус и error.type. Пример:
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "max_tokens is required."
}
}Типы ошибок по статусам
| Статус | OpenAI error.type | Anthropic error.type |
|---|---|---|
| 400 | invalid_request_error | invalid_request_error |
| 401 | authentication_error | authentication_error |
| 402 | insufficient_quota | billing_error |
| 403 | permission_error | permission_error |
| 404 | not_found_error | not_found_error |
| 408 | invalid_request_error | invalid_request_error |
| 413 | invalid_request_error | request_too_large |
| 429 | rate_limit_error | rate_limit_error |
| 500, 502, 503 | api_error | api_error |
Заголовки
x-request-idесть в каждом ответе, включая ошибки. Указывайте его, когда обращаетесь в поддержку.Retry-After(в секундах) приходит сcapacity_exhausted, сmodel_unavailable(секунды до следующей проверки модели, не больше 15), с поминутным и сетевым пробнымrate_limit_exceeded, а также с 503upstream_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 по-прежнему хороший выбор для длинных генераций: первые токены видны сразу, а вывод поступает по мере генерации. Но чтобы избежать тайм-аута, она не нужна.