Ошибки

Каждая ошибка — это HTTP-код 4xx/5xx и JSON с полями type и message. Тело приходит в том же протоколе, что и запрос, и каждый ответ несёт заголовок x-request-id.

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

Форма тела зависит от эндпоинта. Запросы к /v1/messages (и /count_tokens) возвращают ошибку в формате Anthropic. Все остальные эндпоинты (OpenAI-совместимые) — в формате OpenAI. Поле message одинаково; значение error.type следует таксономии своего протокола, поэтому для некоторых кодов различается (например, для 402: invalid_request_error в Anthropic против insufficient_quota в OpenAI). В формате OpenAI поле code содержит внутренний код шлюза (например unauthorized).

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid or missing API key."
  }
}

#Коды ответа

Полный набор кодов, которые эмитит шлюз, с указанием источника (клиент / шлюз / апстрим) и того, безопасен ли повтор. Повторяемые: 429, 502, 504, 529 (для 429 — соблюдайте Retry-After).

#409 — idempotency_conflict

Если вы отправляете свой заголовок Idempotency-Key и запрос с тем же ключом ещё выполняется, шлюз отвечает 409 и НЕ выполняет запрос повторно на апстриме. Не отправляйте его снова — оригинал ещё идёт. Ответ оригинала не воспроизводится (стриминговые тела не переигрываются) — дождитесь его завершения.

{
  "type": "error",
  "error": {
    "type": "idempotency_conflict",
    "message": "a request with this Idempotency-Key is already in flight"
  }
}

#400 — invalid_request_error

Тело запроса некорректно: отсутствует или не строка model, либо max_tokens превышает потолок платформы 32768. Исправьте тело и отправьте снова — повтор без изменений даст ту же ошибку.

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "The requested max output tokens exceeds the platform limit of 32768."
  }
}

Сюда же относится group_not_allowed: запрошена группа исполнения, недоступная вашему аккаунту (префикс вида группа/модель в model, либо группа по умолчанию у ключа). Уберите префикс — или переключите ключ на группу default на странице API-ключи. Повтор без изменений даст ту же ошибку.

#401 — authentication_error

Ключ отсутствует, неверен или отозван. Передайте x-api-key: sk-ev-… или Authorization: Bearer sk-ev-…. Все случаи дают один нейтральный 401 — см. Аутентификацию.

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid or missing API key."
  }
}

#402 — недостаточно средств

Недостаточно средств на счёте, либо достигнут дневной лимит расходов. Это не повторяемая ошибка — повтор не поможет. Пополните баланс (это делает администратор), а дневной лимит сбрасывается в 00:00 UTC. Проверить баланс — GET /v1/balance или страница Биллинг.

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Insufficient balance for this request. Please top up your account to continue."
  }
}

#403 — permission_error

Ключ валиден, но не имеет доступа к запрошенному ресурсу. Используйте ключ с нужным тарифом или обратитесь к администратору. Повтор без изменений не поможет. Тип ошибки — permission_error; точный текст message зависит от случая.

{
  "type": "error",
  "error": {
    "type": "permission_error",
    "message": "..."
  }
}

#404 — not_found_error

Модель не найдена, отключена или у ключа нет к ней доступа. Сверьтесь со списком моделей или вызовите GET /v1/models. Модели доступны на обоих протоколах — и /v1/messages, и /v1/chat/completions.

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "The requested model was not found, is inactive, or is not available on this endpoint."
  }
}

#413 — request_too_large

Тело запроса больше 10 МБ. Уменьшите полезную нагрузку: сократите историю сообщений или уберите крупные вложения. Повтор без изменений не поможет.

{
  "type": "error",
  "error": {
    "type": "request_too_large",
    "message": "The request payload is too large."
  }
}

#429 — rate_limit_error

Превышен лимит запросов для вашего ключа. Ответ несёт заголовок Retry-After (секунды) — дождитесь указанного времени и повторите. Лимиты задаются вашим тарифом. Если лимитер не смог проверить запрос, вернётся 503 с Retry-After: 2.

HTTP/1.1 429 Too Many Requests
Retry-After: 3
x-request-id: req_01ABC...

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "Rate limit exceeded. Please retry after a moment."
  }
}

#503 — временно недоступно

Апстрим-провайдер временно недоступен. Это временная ошибка — повторите с экспоненциальной задержкой. Если присутствует Retry-After, соблюдайте его как нижнюю границу паузы.

{
  "type": "error",
  "error": {
    "type": "api_error",
    "message": "The upstream provider is temporarily unavailable. Please try again."
  }
}

#Повторные попытки

Повторяйте только временные ошибки. Остальные требуют исправления запроса или счёта — повтор лишь сожжёт лимиты.

429 — лимит

Повторять. Дождитесь Retry-After секунд, затем повторите. / Retry. Wait Retry-After seconds, then retry.

503 — апстрим

Повторять с экспоненциальной задержкой (например 1с → 2с → 4с, с джиттером). / Retry with exponential backoff (e.g. 1s → 2s → 4s, with jitter).

502 / 504 / 529 — апстрим

Повторять с задержкой (транспорт/таймаут/перегрузка апстрима — временны). / Retry with backoff (upstream transport/timeout/overload are transient).

409 — idempotency

Не отправлять повторно — оригинал ещё выполняется. / Do not resend — the original is still in flight.

400 / 401 / 402 / 403 / 404 / 413 / 422 / 499 / 501

Не повторять. Исправьте запрос, ключ или баланс. / Do not retry. Fix the request, key, or balance first.

#Дальше