Ошибки LLM API: коды, статусы и правила повторов
Каждая ошибка говорит, что случилось, можно ли повторить запрос и какой у него идентификатор.
Формат ошибки
Методы OpenAI отвечают ошибкой в обёртке error с полями type, code, message, param и request_id. К сообщению обычно добавлена ссылка на строку этой страницы. Исключение: ошибки, текст которых пришёл от модели, идут без ссылки.
Методы Anthropic (/) отвечают в формате 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
{
"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
{
"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_request | 400, 405, 422 | invalid_request_error | нет | Исправьте запрос: поле param, если оно есть, называет причину. Тот же код у 405, когда метод не подходит для пути, и у 422, когда модель отклонила содержимое. |
too_many_images | 400 | invalid_request_error | нет | До оплаченных пополнений на $10 в запросе можно передать не больше 8 изображений, включая ссылки и data URI. Уберите лишние изображения или пополните баланс до этой суммы. Приветственный бонус не учитывается. |
invalid_api_key | 401 | authentication_error | нет | Ключ не передан, неверный, отключён, удалён или просрочен, либо после ротации закончилось окно, в которое работал старый ключ. Передайте действующий ключ в заголовке Authorization: Bearer или x-api-key. |
insufficient_balance | 402 | insufficient_quotaAnthropic: billing_error | нет | Пополните баланс в кабинете. Тот же код у замороженного баланса: его разблокирует поддержка. Как считается нужная сумма, описано в статье о резерве. |
key_limit_exceeded | 402 | insufficient_quotaAnthropic: billing_error | нет | Запрос выходит за лимит расходов ключа. Поднимите лимит в настройках ключа или возьмите другой ключ. |
new_account_limit | 402 | insufficient_quotaAnthropic: billing_error | нет | Аккаунт считается новым, пока сумма оплаченных пополнений меньше $10. Для него отклоняются запросы дороже потолка для новых аккаунтов, а видео недоступно при любой цене. После оплаченных пополнений на $10 ограничения нового аккаунта снимаются. Приветственный бонус в эту сумму не входит. |
model_not_allowed | 403 | permission_error | нет | Этому ключу запрещена модель. Разрешите её в настройках ключа. |
user_blocked | 403 | permission_error | нет | Аккаунт заблокирован. Обратитесь в поддержку. |
request_forbidden | 403 | permission_error | нет | Запрос отклонён по правам. Модель может отказаться обрабатывать содержимое: измените запрос. |
model_not_found | 404 | not_found_error | нет | Такой модели нет. Возьмите идентификатор из каталога. |
not_found | 404 | not_found_error | нет | Путь, файл или задача видео не найдены, либо ссылка на файл истекла. Проверьте базовый адрес, метод и идентификатор. |
request_timeout | 408 | timeout_errorAnthropic: api_error | да | Тело запроса не дошло за 60 с, либо задача видео не уложилась в срок. Повторите. |
request_too_large | 413 | invalid_request_errorAnthropic: request_too_large | нет | Тело больше 32 МиБ. Сократите его. Заголовки больше 64 КиБ получают ответ 431 без JSON, с текстом сервера. |
rate_limited | 429 | rate_limit_error | да | Превышен лимит запросов в минуту для ключа, аккаунта или адреса, либо одновременно идёт слишком много проверок ключей. Этот же код получает адрес, с которого много раз присылали неверные ключи: он временно заблокирован. Подождите Retry-After секунд. Подробности в статье о лимитах. |
free_limit_exceeded | 429 | rate_limit_error | да | Лимит для бесплатного запроса исчерпан. Подождите Retry-After секунд перед повтором. |
pool_exhausted | 429, 503 | rate_limit_error | да | Мощность модели временно занята. Повторите через Retry-After секунд. |
concurrency_limit | 429 | rate_limit_error | да | Слишком много одновременных потоков или запросов на изображения и видео по ключу или аккаунту. Обычный текстовый запрос без потока слот не занимает. Дождитесь завершения текущих и повторите через Retry-After секунд. |
internal_error | 500 | api_error | да | Внутренняя ошибка шлюза. Повторите запрос, при повторении напишите в поддержку с request_id. |
upstream_error | 502 | api_error | да | Модель ответила ошибкой или не ответила. Повторите через Retry-After секунд. |
model_unavailable | 503 | api_errorAnthropic: overloaded_error | нет | Модель недоступна для этого запроса: она приостановлена, для неё нет цены или у её маршрута нет нужного протокола, например Anthropic Messages или Responses. Выберите другую модель или другой формат запроса. Retry-After в ответе есть, но x-should-retry равен false, поэтому автоматически запрос не повторяйте. |
service_unavailable | 503 | api_errorAnthropic: overloaded_error | да | Сервис перегружен или перезапускается. Повторите через Retry-After секунд. Этот код приходит и от шлюза, и от входного прокси, пока шлюз недоступен. |
no_price | 503 | api_errorAnthropic: overloaded_error | нет | Для модели пока нет цены в доступном канале. Выберите другую модель или дождитесь публикации цены. x-should-retry равен false, автоматически запрос не повторяйте. |
upstream_timeout | 504 | timeout_errorAnthropic: 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-ключ не отправляйте.