К содержимому

Ошибки LLM API: коды, статусы и правила повторов

Каждая ошибка говорит, что случилось, можно ли повторить запрос и какой у него идентификатор.

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

Методы OpenAI отвечают ошибкой в обёртке error с полями type, code, message, param и request_id. К сообщению обычно добавлена ссылка на строку этой страницы. Исключение: ошибки, текст которых пришёл от модели, идут без ссылки.

Методы Anthropic (/v1/messages) отвечают в формате Anthropic: type: "error", объект error с типом и сообщением и request_id. Тип ошибки у них тот же, что в таблице ниже, а для нескольких кодов рядом указан тип Anthropic. Если текст ошибки пришёл от модели, тип может быть её собственным: invalid_request_error, not_found_error, permission_error или request_too_large. Поля error.code в формате Anthropic нет: используйте error.type, HTTP-статус и x-request-id.

OpenAI

json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid API key See https://relay-llm.ru/docs/errors#invalid_api_key",
    "param": null,
    "request_id": "01990f3c-7a52-7c1e-9b0a-3d5e8f2a4c61"
  }
}

Anthropic

json
{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key See https://relay-llm.ru/docs/errors#invalid_api_key"
  },
  "request_id": "01990f3c-7a52-7c1e-9b0a-3d5e8f2a4c61"
}

Заголовок x-should-retry в ответах с ошибкой, которые формирует шлюз, говорит, имеет ли смысл повтор. При 429, 502 и 503 заголовок Retry-After задаёт паузу в целых секундах от 1 до 60. Когда шлюз недоступен (обновление, перезапуск), 503 отвечает входной прокси: в нём есть Retry-After, но нет x-should-retry, x-request-id и request_id в теле.

Коды ошибок

КодHTTPТипПовторЧто сделать
invalid_request400, 405, 422invalid_request_errorнетИсправьте запрос: поле param, если оно есть, называет причину. Тот же код у 405, когда метод не подходит для пути, и у 422, когда модель отклонила содержимое.
too_many_images400invalid_request_errorнетДо оплаченных пополнений на $10 в запросе можно передать не больше 8 изображений, включая ссылки и data URI. Уберите лишние изображения или пополните баланс до этой суммы. Приветственный бонус не учитывается.
invalid_api_key401authentication_errorнетКлюч не передан, неверный, отключён, удалён или просрочен, либо после ротации закончилось окно, в которое работал старый ключ. Передайте действующий ключ в заголовке Authorization: Bearer или x-api-key.
insufficient_balance402insufficient_quota
Anthropic: billing_error
нетПополните баланс в кабинете. Тот же код у замороженного баланса: его разблокирует поддержка. Как считается нужная сумма, описано в статье о резерве.
key_limit_exceeded402insufficient_quota
Anthropic: billing_error
нетЗапрос выходит за лимит расходов ключа. Поднимите лимит в настройках ключа или возьмите другой ключ.
new_account_limit402insufficient_quota
Anthropic: billing_error
нетАккаунт считается новым, пока сумма оплаченных пополнений меньше $10. Для него отклоняются запросы дороже потолка для новых аккаунтов, а видео недоступно при любой цене. После оплаченных пополнений на $10 ограничения нового аккаунта снимаются. Приветственный бонус в эту сумму не входит.
model_not_allowed403permission_errorнетЭтому ключу запрещена модель. Разрешите её в настройках ключа.
user_blocked403permission_errorнетАккаунт заблокирован. Обратитесь в поддержку.
request_forbidden403permission_errorнетЗапрос отклонён по правам. Модель может отказаться обрабатывать содержимое: измените запрос.
model_not_found404not_found_errorнетТакой модели нет. Возьмите идентификатор из каталога.
not_found404not_found_errorнетПуть, файл или задача видео не найдены, либо ссылка на файл истекла. Проверьте базовый адрес, метод и идентификатор.
request_timeout408timeout_error
Anthropic: api_error
даТело запроса не дошло за 60 с, либо задача видео не уложилась в срок. Повторите.
request_too_large413invalid_request_error
Anthropic: request_too_large
нетТело больше 32 МиБ. Сократите его. Заголовки больше 64 КиБ получают ответ 431 без JSON, с текстом сервера.
rate_limited429rate_limit_errorдаПревышен лимит запросов в минуту для ключа, аккаунта или адреса, либо одновременно идёт слишком много проверок ключей. Этот же код получает адрес, с которого много раз присылали неверные ключи: он временно заблокирован. Подождите Retry-After секунд. Подробности в статье о лимитах.
free_limit_exceeded429rate_limit_errorдаЛимит для бесплатного запроса исчерпан. Подождите Retry-After секунд перед повтором.
pool_exhausted429, 503rate_limit_errorдаМощность модели временно занята. Повторите через Retry-After секунд.
concurrency_limit429rate_limit_errorдаСлишком много одновременных потоков или запросов на изображения и видео по ключу или аккаунту. Обычный текстовый запрос без потока слот не занимает. Дождитесь завершения текущих и повторите через Retry-After секунд.
internal_error500api_errorдаВнутренняя ошибка шлюза. Повторите запрос, при повторении напишите в поддержку с request_id.
upstream_error502api_errorдаМодель ответила ошибкой или не ответила. Повторите через Retry-After секунд.
model_unavailable503api_error
Anthropic: overloaded_error
нетМодель недоступна для этого запроса: она приостановлена, для неё нет цены или у её маршрута нет нужного протокола, например Anthropic Messages или Responses. Выберите другую модель или другой формат запроса. Retry-After в ответе есть, но x-should-retry равен false, поэтому автоматически запрос не повторяйте.
service_unavailable503api_error
Anthropic: overloaded_error
даСервис перегружен или перезапускается. Повторите через Retry-After секунд. Этот код приходит и от шлюза, и от входного прокси, пока шлюз недоступен.
no_price503api_error
Anthropic: overloaded_error
нетДля модели пока нет цены в доступном канале. Выберите другую модель или дождитесь публикации цены. x-should-retry равен false, автоматически запрос не повторяйте.
upstream_timeout504timeout_error
Anthropic: api_error
нетМодель не прислала ни байта вовремя: за 90 с в потоке и за 120 с без потока. В запросе со stream: true x-should-retry равен true, без потока равен false: для длинных ответов включайте поток.

Повторы

Повторяйте запрос, только когда x-should-retry равен true, и выдерживайте Retry-After, если он пришёл. Ответ 503 без x-should-retry пришёл от входного прокси, а не от шлюза: повторите его с паузой из Retry-After.

Повтор обрабатывается как самостоятельный запрос, и его стоимость зависит от его собственного исхода. Что списывается, когда ответа нет:

  • Если шлюз ответил ошибкой до первого байта ответа модели (кроме upstream_timeout), запрос не списывается.
  • Если шлюз не дождался первого байта (upstream_timeout), у текстовых запросов списывается оценка входа. Её же списывают, когда вы закрыли соединение, пока модель не начала отвечать, а запрос уже ушёл к ней: например по своему ограничению времени ожидания. Если запрос к модели не успел уйти, не списывается ничего.

Поэтому делайте повтор явным действием с ограниченным числом попыток, а не бесконечным автоповтором.

Когда Retry-After нет, например при 500 и 504, увеличивайте паузу между попытками.

Обращение в поддержку

В обращении укажите request_id из тела ошибки или заголовка x-request-id, время и код ошибки. У 503 от входного прокси request_id нет: тогда достаточно времени и кода. Полный API-ключ не отправляйте.

Написать на support@relay-llm.ru

Готовы? Три шага, чтобы начатьВойдите в консоль · пополните баланс · создайте API Key