Ошибки и лимиты

Ошибки бывают двух видов. Наши — когда запрос остановили мы: ключ, баланс, лимиты, модель. Ошибки провайдера приходят как есть, в формате его протокола: Claude Code и Codex узнают их и сами повторяют запрос, когда это имеет смысл.

Если нужен не справочник, а разбор по симптому — «пришёл 401, что делать», — смотри «Решение проблем».

Формат#

Наша ошибка — JSON в форме, которую разбирают клиенты и Anthropic, и OpenAI. Смотри на error.code: HTTP-статус у разных причин бывает общий.

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "key rate limit exceeded"
  }
}

Заголовок x-should-retry говорит, есть ли смысл повторять: true или false. Когда ждать нужно определённое время, рядом стоит retry-after в секундах. Если заголовок и колонка «Повторять» в таблице ниже расходятся, верь заголовку: у одного кода бывают разные причины. Ответы 401 invalid_api_key и 503 authentication_unavailable приходят без этого заголовка.

Два отказа приходят не в этой форме, а коротким текстом, без JSON и без error.code: 429 лимита по IP-адресу (с заголовком retry-after) и 413 для запроса, у которого заявленный в Content-Length размер тела больше 32 МБ. Оба описаны в лимитах сервиса.

Коды#

Код request_too_large приходит с двумя статусами: 413 — тело больше допустимого размера, 400 — запрос больше минутного лимита токенов ключа. В форме JSON ответ 413 приходит, когда размер тела заранее не объявлен (chunked); обычный запрос с Content-Length получит 413 текстом.

Ошибку 524 отдаёт не наш API, а Cloudflare перед ним: запрос без стрима ждал ответа дольше примерно двух минут. Длинные ответы запрашивай стримом — справочник API.

Коды в журнале запросов#

Запрос, который мы отклонили до отправки провайдеру — 401, 402, 403, наши 400 и 429, — в журнал кабинета не попадает и ничего не стоит. Запросы, дошедшие до провайдера, в журнале есть все, с HTTP-статусом и кодом ошибки. Кроме кодов из таблицы выше там встречаются:

Ошибкой в статистике считается только сбой на нашей стороне: ответ 5xx или оборванный стрим. Строки с ответом 4xx видны в журнале со своим статусом, но в счётчик ошибок не входят.

Лимиты ключа#

У ключа могут быть:

• запросы в минуту (rpm) — сверх лимита ключ отвечает 429 rate_limit_exceeded;
• токены в минуту (tpm) — считаются входные токены по оценке: размер тела запроса в байтах, делённый на 4. Сверх лимита — тот же 429; запрос, который один больше всего лимита, — 400 request_too_large;
• месячный лимит расходов в долларах — когда резерв под запрос в него не помещается, ключ отвечает 429 monthly_limit_exceeded до начала следующего месяца;
• список разрешённых моделей — остальные получают 403 model_not_allowed и не видны ключу в GET /v1/models.

Лимиты задаются при создании ключа на странице «Ключи» и меняются там же в любой момент: сам ключ остаётся прежним, а новые значения действуют со следующего запроса. Запрос, который уже выполняется, доработает со старыми лимитами. Отдельный ключ на каждый инструмент или проект — простой способ знать, кто сколько тратит. Подробнее — в разделе «Ключи и лимиты».

Лимиты сервиса#

Они действуют на любой ключ, какие бы лимиты у него ни стояли:

• не больше 120 запросов и 2 000 000 токенов в минуту на ключ — действует меньшее из этого потолка и лимита самого ключа;
• с одного IP-адреса — не больше 60 запросов в минуту, 300 за пять минут и 1 200 в час на каждый адрес API (/v1/messages, /v1/chat/completions и остальные считаются отдельно), сколько бы ключей ни было. С одной машины этот лимит строже лимита ключа. Сверх него приходит 429 текстом, без JSON, с заголовком retry-after;
• не больше 4 одновременных запросов на ключ — следующий получит 429 concurrent_requests;
• тело запроса — до 32 МБ, иначе 413: текстом, если размер объявлен в Content-Length, и с кодом request_too_large, если нет;
• один запрос — не дольше 30 минут;
• не больше 20 активных ключей на аккаунт — создание следующего вернёт 409; отозванные ключи не считаются.