Начало · Ошибки

Коды ответов и лимиты

Ошибка всегда приходит в формате того протокола, по которому пришёл запрос: OpenAI-клиенту — в форме OpenAI, Anthropic-клиенту — в форме Anthropic. Библиотеке не нужно знать, что перед ней шлюз.

Коды#

Код	Что случилось и что делать
`401`	Ключа нет, он отозван или истёк. Проверьте заголовок и выпустите новый ключ в настройках
`402`	Не хватает баланса на запрос. Пополните в тарифах
`403`	Код `PLAN` — тариф не даёт API. Нужен «Про»
`403`	Код `SCOPE` — ключу не выдано право на этот метод; `IP_DENIED` — запрос пришёл с адреса вне списка, разрешённого ключу; блокировка аккаунта — тоже сюда
`404`	Модели нет в каталоге или она выключена. Сверьтесь с GET /v1/models
`415`	Модель не принимает картинки. См. картинки
`422`	Тело не прошло проверку: не тот тип поля, отрицательный max_tokens, пустой messages
`429`	Исчерпан дневной лимит ключа или аккаунта. Ждать до следующих суток или поднять лимит ключа
`502`	Провайдер модели ответил ошибкой. Стоит повторить: при 502 списания не происходит

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

Chat Completions и каталог отвечают в форме OpenAI:

json

{
  "error": {
    "message": "Требуется тариф «Про»",
    "type": "forbidden",
    "code": "PLAN"
  }
}

/v1/messages — в форме Anthropic, потому что клиенты Claude разбирают именно её:

json

{
  "type": "error",
  "error": {
    "type": "permission_error",
    "message": "Требуется тариф «Про»"
  }
}

Машинный признак — поле code в форме OpenAI и error.type в форме Anthropic. Текст message человеческий и может меняться: не разбирайте его.

Ошибка внутри стрима#

Если запрос уже принят и стрим начался, код ответа поменять нельзя — он уже 200. Поэтому сбой приходит событием внутри потока:

text

data: {"error":{"message":"…","type":"server_error","code":"upstream"}}

В Anthropic-протоколе это событие error. Обработчик стрима должен проверять поле error в каждом куске, а не только код ответа — иначе оборванная генерация будет выглядеть как успешно законченная.

Ограничения#

Тело запроса — до 32 МБ. Хватает, чтобы прислать весь контекст проекта одним запросом.
max_tokens — до 200 000, но не больше, чем допускает сама модель.
Дневной лимит задаётся у каждого ключа отдельно в настройках. Сверх него — 429.
Ключ можно ограничить по IP: запросы с других адресов получат 403 IP_DENIED.

Как повторять#

Повторять стоит только 429, 502 и сетевые обрывы — с задержкой, увеличивающейся вдвое. 401, 402, 403, 404, 415 и 422 при повторе вернут то же самое: их причина в запросе или в аккаунте, а не во временном сбое.

Списание при обрыве

Если генерация оборвалась на середине, списываются токены, которые провайдер успел посчитать, — то есть за полученную часть. Полностью неудачный запрос (502 до первого токена) не списывается.