Ошибки Claude API: 400, 401, 429, 529 и как их исправить

Коротко

Claude API сообщает о каждой ошибке в виде JSON с HTTP-статусом и полем error.type: 400 invalid_request_error (что-то не так в теле запроса), 401 authentication_error (ключ не передан или неверен), 403 permission_error, 404 not_found_error (неверный путь или ID модели), 413 request_too_large, 429 rate_limit_error, 500 api_error и 529 overloaded_error. Ошибки 4xx исправляются изменением запроса — тот же запрос без изменений снова завершится ошибкой; 429, 500, 503 и 529 повторяйте с экспоненциальной задержкой (backoff) и учитывайте заголовок retry-after, если он есть. В APIVAI действуют те же коды плюс 402 insufficient_quota, когда исчерпан бюджет ключа; лимит по умолчанию — 60 запросов в минуту на ключ. Большинство ошибок 404 вызваны базовым URL: для формата Anthropic используйте https://api.apivai.com, для формата OpenAI — https://api.apivai.com/v1.

Как выглядит ответ Claude API с ошибкой?

API Anthropic возвращает ошибки в JSON с объектом error верхнего уровня, в котором всегда есть type и message, — так описано на официальной странице ошибок Claude API. APIVAI отвечает в том же формате:

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "Not found. Check the model name and the endpoint path."
  }
}

Формат OpenAI (POST /v1/chat/completions и /v1/responses) традиционно использует {"error": {"message": "...", "type": "...", "param": null, "code": "..."}}. В APIVAI ошибки на этих эндпоинтах приходят в том же теле, что показано выше. SDK и инструменты OpenAI читают error.message и error.type — эти поля есть всегда; для ошибок 400, 404 и 413 в теле также могут быть code и param, если они указывают, какое поле не прошло проверку.

Всегда начинайте с error.message. При проблемах с запросом (400, 404, 413) там обычно названо конкретное поле или модель.

Что означают коды ошибок Claude API?

HTTP	error.type	Что значит	Что делать	Повторять?
400	`invalid_request_error`	Неверное тело или параметры	Исправить поле из сообщения	Нет
401	`authentication_error`	Ключ не передан или недействителен	Проверить ключ и заголовок	Нет
402	`insufficient_quota`	Бюджет ключа исчерпан (APIVAI)	Добавить бюджет ключу в Dashboard	Нет
403	`permission_error`	Аккаунт отключён или ресурс недоступен	Написать в поддержку	Нет
404	`not_found_error`	Неверный путь, базовый URL или ID модели	Проверить `/v1` и ID модели	Нет
413	`request_too_large`	Слишком большое тело запроса	Отправлять меньше данных	Нет
429	`rate_limit_error`	Слишком много запросов в минуту или бюджет ключа исчерпан	Подождать; прочитать сообщение	Да, с backoff
500	`api_error`	Непредвиденная ошибка сервера	Повторить с backoff	Да
503 / 529	`overloaded_error`	Временная перегрузка	Повторить с backoff	Да

В официальном списке Anthropic есть также 402 billing_error (проблема с оплатой в аккаунте Anthropic), 409 conflict_error и 504 timeout_error. Для длинных генераций официальная рекомендация против тайм-аутов — использовать стриминг. В APIVAI код 402 всегда означает, что исчерпан бюджет используемого ключа.

Почему возникает 401 «invalid x-api-key» или «Invalid API key»?

401 authentication_error означает, что запрос дошёл до API, но ключ не принят. APIVAI возвращает «Missing API key.», если ключ вообще не передан, и «Invalid API key.», если ключ не принадлежит вам.

Проверьте по порядку:

Заголовок. Формат Anthropic обычно передаёт x-api-key: <key>, формат OpenAI — Authorization: Bearer <key>. APIVAI принимает любой из них в обоих форматах, так что 401 здесь связан с самим ключом, а не с выбором заголовка.
Текст ключа. Скопируйте его заново из Dashboard: часто теряется символ или в поле попадают пробел или кавычки.
Отправляется другой ключ. Старая переменная окружения ANTHROPIC_API_KEY или OPENAI_API_KEY может перекрывать ключ, введённый в настройках инструмента. Какие переменные читает Claude Code, описано в руководстве по настройке Claude Code.
Ключ удалён или перевыпущен. Перевыпущенный ключ заменяет старый — обновите его во всех инструментах.

403 permission_error с текстом «This account is disabled. Contact support.» означает, что ключ действителен, но аккаунт отключён; замена ключа не поможет — напишите в поддержку.

Как исправить 429 rate_limit_error и 402 insufficient_quota?

В APIVAI у каждого ключа два ограничения:

Частота запросов. По умолчанию — 60 запросов в минуту на ключ. Агенты, которые делают много параллельных вызовов, могут его превысить. Уменьшите параллелизм, повторяйте с backoff или попросите поддержку поднять лимит.
Бюджет. У каждого ключа свой бюджет, который берётся из баланса аккаунта при создании ключа или при пополнении его бюджета. Когда бюджет исчерпан, запросы завершаются ошибкой 402 insufficient_quota («This key has no budget left. Add budget to the key in the dashboard.») или 429, в сообщении которой сказано, что бюджет ключа израсходован.

Ошибки бюджета не проходят от повторов. Откройте Dashboard и добавьте бюджет этому ключу. Если баланс аккаунта тоже пуст, сначала пополните его (от $10). На балансе могут быть деньги, а у отдельного ключа — нет: для его запросов значение имеет собственный бюджет ключа. Актуальные цены за токены — на странице тарифов.

Что такое overloaded_error (529) и как правильно повторять запросы?

overloaded_error означает временную перегрузку сервиса. Она не вызвана вашим запросом, и тот же запрос обычно проходит чуть позже. APIVAI возвращает её как 529 или как 503 с тем же типом overloaded_error. 500 api_error обрабатывается так же.

Правильный подход — экспоненциальная задержка: подождать около 1 с, затем 2, 4, 8 с, добавить немного случайного разброса (jitter) и остановиться после нескольких попыток. Если в ответе есть заголовок retry-after, ждите не меньше указанного; APIVAI передаёт retry-after и retry-after-ms, когда они заданы.

Официальные SDK Anthropic уже делают это: по умолчанию они дважды повторяют ошибки соединения, 429 и 5xx с экспоненциальной задержкой и учитывают retry-after. Достаточно увеличить max_retries:

import anthropic

client = anthropic.Anthropic(
    base_url="https://api.apivai.com",
    api_key="YOUR_APIVAI_KEY",
    max_retries=5,  # default is 2
)

try:
    msg = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=4096,
        messages=[{"role": "user", "content": "Hello"}],
    )
    print("".join(b.text for b in msg.content if b.type == "text"))
except anthropic.APIStatusError as e:
    print(e.status_code, e.response.headers.get("request-id"), e.message)

Без SDK хватит небольшого цикла. Он повторяет только временные коды и останавливается, если 429 связан с бюджетом:

import random, time, requests

RETRY = {429, 500, 503, 529}

def post_with_backoff(url, headers, body, attempts=5):
    for i in range(attempts):
        r = requests.post(url, headers=headers, json=body, timeout=600)
        if r.status_code not in RETRY or "budget" in r.text:
            return r
        wait = float(r.headers.get("retry-after", 2 ** i))
        time.sleep(wait + random.random())
    return r

Почему возникает 404 not_found_error?

Почти всегда виноват базовый URL или ID модели:

Формат Anthropic: базовый URL https://api.apivai.com без /v1. Anthropic SDK и Claude Code сами добавляют /v1/messages, поэтому https://api.apivai.com/v1 превращается в /v1/v1/messages и не работает.
Формат OpenAI: базовый URL https://api.apivai.com/v1, ровно один /v1. Без него запрос уходит на /chat/completions, и APIVAI отвечает «Unknown endpoint».
Не тот хост: запросы на apivai.com вместо api.apivai.com получают 404 с сообщением «Wrong base URL» и обоими правильными адресами.
ID модели: используйте точный ID, например claude-sonnet-4-6, а не отображаемое название. Список ID, доступных вашему ключу:

curl https://api.apivai.com/v1/models \
  -H "Authorization: Bearer YOUR_APIVAI_KEY"

Модели Claude работают в обоих форматах, модели GPT, например gpt-5.5, — только в формате OpenAI. Подробнее о форматах: прокси Claude API и OpenAI-совместимый API.

Почему возникает 400 invalid_request_error?

400 означает, что API понял запрос, но отклонил его содержимое. Причина указана в сообщении. Частые случаи:

В запросе формата Anthropic нет max_tokens (там это обязательный параметр).
Диалог заканчивается сообщением ассистента (prefill). Модели Claude 4.6 и новее его отклоняют — последним должно быть сообщение пользователя.
Устаревшая настройка thinking: новые модели, например claude-opus-5-5, отклоняют thinking: {"type": "enabled"} и ожидают adaptive thinking. Уберите поле thinking, чтобы использовать значение по умолчанию.
Блоки thinking изменены или удалены перед повторной отправкой в цикле с инструментами. Возвращайте их точно в том виде, в каком получили.

Похожая проблема ошибкой вообще не является: пустые или обрезанные ответы. Thinking включён по умолчанию, и его токены считаются выходными, поэтому маленький max_tokens может закончиться до появления текста. Ответ завершается с stop_reason: "max_tokens" (или finish_reason: "length" в формате OpenAI). Увеличьте max_tokens до 4096 или больше.

413 request_too_large означает, что слишком велико само тело запроса. Лимит Anthropic для Messages API — 32 МБ. Обычные причины — большие файлы в base64 и очень длинная история: отправляйте меньше файлов или файлы поменьше, сокращайте старые реплики.

Как ошибки проявляются при стриминге?

С "stream": true HTTP-статус равен 200 сразу после начала потока, и более поздний сбой изменить его уже не может. Вместо этого ошибка приходит событием внутри потока. В документации Anthropic по стримингу приведён такой пример:

event: error
data: {"type": "error", "error": {"type": "overloaded_error", "message": "Overloaded"}}

Если поток через APIVAI обрывается до завершения, APIVAI отправляет event: error с api_error и текстом «The response was interrupted. Please retry.», а не закрывает поток молча, — поэтому SDK выбрасывают исключение, а не возвращают половину ответа. Относитесь к этому как к 500: повторите весь запрос.

Как найти request ID?

Ответы могут содержать заголовок request-id (некоторые сервисы используют x-request-id); APIVAI передаёт его, когда он есть. Выведите заголовки через curl:

curl -sS -D - https://api.apivai.com/v1/messages \
  -H "x-api-key: YOUR_APIVAI_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hi"}]}'

В Python SDK у успешного ответа есть msg._request_id, а у исключения — e.response.headers. При обращении в поддержку укажите ID, время и текст ошибки.

Какие причины встречаются чаще всего?

Симптом	Вероятная причина	Решение
404 на каждый запрос	`/v1` нет, лишний или продублирован	Anthropic: `https://api.apivai.com`; OpenAI: `https://api.apivai.com/v1`
401 с ключом, который выглядит верным	Старая переменная окружения отправляет другой ключ	Удалить её или заменить ключом APIVAI
404 или 400 с названием модели	Опечатка или отображаемое имя	Скопировать ID из `GET /v1/models`
Пустые или обрезанные ответы	Мало `max_tokens` при thinking	4096 или больше
413	Большие файлы в теле	Отправлять меньше данных
429 во время работы агента	Больше 60 запросов в минуту	Снизить параллелизм, backoff
402 или 429 про бюджет	Бюджет ключа исчерпан	Добавить бюджет ключу
529 / 503	Временная перегрузка	Повторить с backoff

Настройка конкретных инструментов описана в документации и в руководствах вроде Cline с Claude и GPT.

Частые вопросы

Нужно ли повторять запрос после 400 или 401?

Нет. Ошибки 4xx, кроме 429, говорят о проблеме в запросе или ключе, и тот же запрос завершится так же. Сначала устраните причину.

Чем 429 отличается от 529?

429 касается ваших собственных лимитов: запросов в минуту, а в APIVAI ещё и бюджета ключа. 529 overloaded_error — временная перегрузка, не зависящая от вашего использования; и 429 из-за частоты запросов, и 529 повторяют с backoff.

Повторяет ли Anthropic SDK запросы автоматически?

Да. По умолчанию он дважды повторяет ошибки соединения, 429 и 5xx с экспоненциальной задержкой и учитывает retry-after. Чтобы изменить это, задайте max_retries у клиента, а 0 отключает повторы.

Почему ответ пустой, а ошибки нет?

Thinking израсходовал весь max_tokens до видимого текста. Увеличьте max_tokens до 4096 или больше; токены thinking оплачиваются как выходные.

На балансе есть деньги — почему я получаю 402?

Баланс и бюджет ключа — разные вещи. Каждый ключ тратит только свой бюджет; добавьте бюджет этому ключу в Dashboard.

Создайте аккаунт, пополните баланс от $10 и создайте ключ, чтобы вызывать Claude и GPT через один API.