← Блог
Claude APIErrorsTroubleshooting

Ошибки 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 запросов в минуту и 5 одновременно (остальные ждут в очереди). Большинство ошибок 404 вызваны базовым URL: в формате Anthropic Claude Code и Anthropic SDK принимают https://api.apivai.com, а некоторые инструменты (Continue, Chatbox, OpenCode, Kilo Code) добавляют только /messages и требуют https://api.apivai.com/v1 (главное, чтобы запросы попадали на /v1/messages); для формата 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?

HTTPerror.typeЧто значитЧто делатьПовторять?
400invalid_request_errorНеверное тело или параметрыИсправить поле из сообщенияНет
401authentication_errorКлюч не передан или недействителенПроверить ключ и заголовокНет
402insufficient_quotaБюджет ключа исчерпан или слишком мал для этой модели (APIVAI)Добавить бюджет ключу в Dashboard или взять модель дешевлеНет
403permission_errorАккаунт отключён или ресурс недоступенНаписать в поддержкуНет
404not_found_errorНеверный путь, базовый URL или ID моделиПроверить /v1 и ID моделиНет
413request_too_largeСлишком большое тело запросаОтправлять меньше данныхНет
429rate_limit_errorСлишком много запросов в минуту или одновременно на одном ключеПодождать; распределить параллельную работу по нескольким ключамДа, с backoff
500api_errorНепредвиденная ошибка сервераПовторить с backoffДа
503 / 529overloaded_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 запросов в минуту, и одновременно выполняются 5 запросов: остальные ждут свободного места в очереди, а когда на одном ключе открыто 20 запросов, новые сразу получают 429. Агенты, которые делают много параллельных вызовов, могут упереться в любой из этих лимитов. Уменьшите параллелизм, повторяйте с backoff или распределите параллельную работу по нескольким ключам (у каждого ключа свои лимиты).
  • Бюджет. У каждого ключа свой бюджет, который берётся из баланса аккаунта при создании ключа или при пополнении его бюджета. Когда бюджет исчерпан или его остатка мало для запрошенной модели, запросы завершаются ошибкой 402 insufficient_quota («Not enough budget left on this key for this model. Add budget to the key in the dashboard, or use a cheaper model.»); исчерпанный бюджет даёт 402, а не 429. Низкий бюджет ещё и ограничивает, сколько запросов к дорогой модели может выполняться одновременно на этом ключе; сверх этого запросы немного ждут, а затем получают 429 с указанием, сколько позволяет бюджет, — пополнение бюджета увеличивает это число. Самые дорогие модели (Opus, Fable и Sonnet 4.6) отклоняются, когда на ключе остаётся всего несколько долларов, даже для крошечного запроса, а более дешёвые (Sonnet 5.5, Haiku, GPT) на том же ключе работают. Ключи с остатком меньше $5 Dashboard помечает как «Low budget».

Ошибки бюджета не проходят от повторов. Откройте Dashboard и добавьте бюджет этому ключу (для моделей уровня Opus оставляйте запас в несколько долларов) или переключитесь на модель дешевле. Если баланс аккаунта тоже пуст, сначала пополните его (от $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 хватит небольшого цикла. Он повторяет только временные коды (ошибка бюджета 402 возвращается сразу) и отправляет запрос с "stream": true: запрос без стриминга, который длится дольше примерно 100 секунд, обрывается на границе сети с кодом 524, поэтому длинным генерациям нужен стриминг. В r.text тогда приходят события server-sent events:

import random, time, requests

RETRY = {429, 500, 503, 529}

def post_with_backoff(url, headers, body, attempts=5):
    body = {**body, "stream": True}  # non-streaming requests over ~100 s end in 524
    for i in range(attempts):
        r = requests.post(url, headers=headers, json=body, timeout=600)
        if r.status_code not in RETRY:
            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: Claude Code и Anthropic SDK принимают https://api.apivai.com без /v1, потому что сами добавляют /v1/messages; https://api.apivai.com/v1 превратится в /v1/v1/messages и не сработает. Некоторые инструменты (Continue, Chatbox, OpenCode, Kilo Code) добавляют только /messages и требуют https://api.apivai.com/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-6.1-sol, — только в формате 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 изменены или удалены перед повторной отправкой в цикле с инструментами. Возвращайте их точно в том виде, в каком получили.

Похожая проблема ошибкой вообще не является: пустые или обрезанные ответы. Модели Claude могут рассуждать (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 (Claude Code, Anthropic SDK) или https://api.apivai.com/v1 (Continue, Chatbox, OpenCode, Kilo Code), чтобы запросы шли на /v1/messages; OpenAI: https://api.apivai.com/v1
401 с ключом, который выглядит вернымСтарая переменная окружения отправляет другой ключУдалить её или заменить ключом APIVAI
404 или 400 с названием моделиОпечатка или отображаемое имяСкопировать ID из GET /v1/models
Пустые или обрезанные ответыМало max_tokens при thinking4096 или больше
413Большие файлы в телеОтправлять меньше данных
429 во время работы агентаБольше 60 запросов в минуту или слишком много одновременноСнизить параллелизм, backoff или взять несколько ключей
402Бюджет ключа исчерпан или мал для этой моделиДобавить бюджет ключу или взять модель дешевле
529 / 503Временная перегрузкаПовторить с backoff
524Запрос без стриминга длился дольше 100 сОтправлять с "stream": true

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

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

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

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

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

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

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

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

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

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

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

Баланс и бюджет ключа — разные вещи. Каждый ключ тратит только свой бюджет; добавьте бюджет этому ключу в Dashboard. Если на ключе осталось всего несколько долларов, запросы к самым дорогим моделям (Opus, Fable, Sonnet 4.6) тоже получают 402, а к более дешёвым проходят: добавьте запас в несколько долларов или возьмите модель дешевле. Ключ перестаёт работать, когда на нём ещё остаётся небольшая сумма; она не пропадает: при удалении ключа остаток возвращается на баланс аккаунта.

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

Готовы начать?

Получите API-ключ за 30 секунд. Оплата по факту использования Claude и GPT.

Начать