Коротко
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?
| 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 запросов в минуту, и одновременно выполняются 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 при thinking | 4096 или больше |
| 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.