Ошибки Claude API: 401, 429, 529 и что с ними делать

Q: Что означает ошибка 529 у Claude API?

overloaded_error — сервис перегружен запросами. Это не ваш лимит и не проблема вашего кода: в пиковые часы мощности вендора кончаются. Помогает повтор с нарастающей задержкой, а если задача терпит — переключение на другую модель.

Q: Почему ответ Claude обрывается на середине?

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

10 августа 2026 · 8 минут чтения

Коротко

Ошибки Claude API делятся на три группы, и лечатся они принципиально по-разному:

Ваши — 400, 401, 403, 404, 413. Что-то не так с запросом, ключом или именем модели. Ретраи бесполезны, надо чинить код.
Лимиты — 429. Вы упёрлись в потолок скорости. Ретраи помогают, но только с правильной паузой.
Не ваши — 500, 529. Проблема на стороне сервиса. Единственная рабочая стратегия — повтор с нарастающей задержкой.

И отдельно — самый частый случай, который вообще не ошибка: ответ обрывается на середине, потому что упёрся в max_tokens. Кода ошибки нет, HTTP 200, а текст неполный. Разберём и это.

Коды по порядку

`401` — `authentication_error`

Ключ не принят. Причины по убыванию частоты:

Ключ скопирован с лишним пробелом или переносом. Самая частая и самая обидная. Проверьте len(key).
Ключ отозван или пересоздан, а в окружении остался старый.
Ключ подставлен не в тот заголовок. У Anthropic напрямую это x-api-key, у OpenAI-совместимых шлюзов — Authorization: Bearer. Библиотека обычно решает это за вас, но при ручном curl перепутать легко.
Переменная окружения не долетела до процесса. echo $ANTHROPIC_API_KEY в той же оболочке, где запускается код, а не в соседней вкладке.

`403` — `permission_error`

Ключ валиден, но не имеет права на это действие. Обычно — ограниченная область действия ключа или модель, недоступная аккаунту.

Если вы работаете через шлюз, проверьте область ключа: у нас, например, ключ можно выпустить только на чат, только на изображения или только на видео, и обращение не в свою область вернёт отказ.

`404` — `not_found_error`

Почти всегда — опечатка в имени модели. Идентификаторы у Anthropic длинные и версионированные, у шлюзов короткие, и при переезде их путают.

Лечится не гаданием, а запросом списка:

curl -s https://api.altrouter.ai/v1/models | jq '.data[].id'

Берите строку оттуда, а не из статьи в интернете — статьи протухают.

`400` — `invalid_request_error`

Запрос не прошёл валидацию. Три типичных повода:

Кончились деньги. Часть сервисов возвращает это именно как 400 с текстом про баланс, а не как отдельный код. Читайте сообщение, а не только номер.
Контекст длиннее окна. У моделей Claude окно 200 000 токенов. Сумма промпта, истории и max_tokens должна в него влезать.
Неверная структура сообщений. Роли обязаны чередоваться, пустой content не принимается, системный промпт передаётся отдельным полем, а не первым сообщением с ролью system.

`413` — запрос слишком большой

Отдельный случай от предыдущего: дело не в токенах, а в размере тела запроса — обычно из-за картинок, вложенных в base64. Уменьшайте изображение или передавайте ссылкой.

`429` — `rate_limit_error`

Вы превысили лимит скорости. У Anthropic их два независимых: по запросам в минуту и по токенам в минуту. Второй упирается раньше, чем ждут: десяток запросов с длинным контекстом выберет токенный лимит, пока счётчик запросов ещё далеко от потолка.

Что делать:

Смотрите заголовки ответа. В них написано, какой именно лимит исчерпан и когда сбросится. Это точнее любых догадок.
Ретраи с экспоненциальной задержкой и джиттером. Без джиттера параллельные воркеры синхронно упрутся в тот же лимит через ту же секунду.
Не долбите в цикле. Ретраи без паузы — это способ продлить 429, а не выйти из него.
Сократите контекст. Обрезка истории диалога снижает расход токенов в минуту, а заодно и счёт.

`500` — `api_error`

Внутренняя ошибка сервиса. Повторяйте с задержкой; если воспроизводится стабильно на одном и том же запросе — дело всё-таки в запросе, посмотрите на него внимательнее.

`529` — `overloaded_error`

Специфичный для Anthropic код: сервис перегружен. Это не ваш лимит и не ваша ошибка — модель популярна, и в пиковые часы мощности кончаются.

Единственная рабочая стратегия: повтор с нарастающей задержкой. И, если задача терпит, — фолбэк на другую модель. У нас это одна строка: запрос уходит на резервного провайдера или на соседнюю модель, вместо того чтобы вернуть пользователю ошибку.

Ответ оборвался на середине — это не ошибка

Самая частая жалоба, которая приходит под видом «баг в API».

Код 200, ошибки нет, но текст обрывается на полуслове. Причина в max_tokens: модель упёрлась в потолок выходных токенов и остановилась. В ответе это видно по причине остановки — max_tokens вместо end_turn.

Всегда проверяйте причину остановки, а не только наличие текста. Логика вида «если пришёл ответ — значит всё хорошо» рано или поздно отдаст пользователю обрубок.

Отдельная тонкость, если включено расширенное рассуждение: часть выходных токенов уходит на внутренние размышления, которых вы в ответе не видите, но которые считаются в тот же лимит. Ответ на три строки может съесть тысячи токенов и упереться в потолок раньше, чем вы ожидали.

🔴 Практическая деталь нашего шлюза: запрос без явного max_tokens мы ограничиваем значением 4096. Это защита от неограниченного расхода — сценарий, где забытый параметр съедает баланс за ночь, встречается чаще, чем хотелось бы. Если вам нужен длинный ответ, max_tokens надо передать явно.

Ошибки, которых нет у Anthropic, но есть у шлюзов

Если вы ходите к Claude не напрямую, добавляется свой слой.

402 или сообщение о нехватке средств — на балансе шлюза кончились деньги. Ключ при этом валиден.
404 на модель, которая точно существует — модель есть у вендора, но её нет в каталоге шлюза. Сверяйтесь со списком шлюза, а не с документацией Anthropic.
HTML вместо JSON — вы не дошли до приложения, вас остановил защитный фильтр по дороге. Разбор этого случая со всеми проверками — в отдельной статье.

Правило разбора простое: сначала смотрим, JSON перед нами или HTML. JSON — отвечало приложение, читаем type и сообщение. HTML — до приложения запрос не дошёл, и коды из документации тут ни при чём.

Claude Code: честно о том, что не работает

Раз уж речь про ошибки — про ту, которую нельзя починить настройками.

Claude Code ходит в Anthropic-совместимый эндпоинт /v1/messages. У нас входящего /v1/messages сейчас нет — только OpenAI-совместимый /v1/chat/completions. Это значит, что подставить наш адрес в переменные Claude Code и получить работающий агент не выйдет: вы упрётесь в 404, и это не опечатка в конфиге.

Что работает с нашим ключом уже сегодня — любой клиент с настраиваемым OpenAI-совместимым адресом: библиотека openai, редакторы с полем base URL, оболочки вроде Open WebUI и LibreChat, автоматизации.

Минимальный обработчик

Практический каркас, покрывающий всё вышеописанное:

import time, random
from openai import OpenAI

client = OpenAI(api_key="sk-...", base_url="https://api.altrouter.ai/v1")

def ask(messages, model="claude-sonnet-5", tries=5):
    for i in range(tries):
        try:
            r = client.chat.completions.create(
                model=model, messages=messages, max_tokens=4096,
            )
            if r.choices[0].finish_reason == "length":
                print("ответ обрезан: поднимите max_tokens")
            return r.choices[0].message.content
        except Exception as e:
            code = getattr(e, "status_code", None)
            if code in (429, 500, 529) and i < tries - 1:
                time.sleep(2 ** i + random.random())   # задержка + джиттер
                continue
            raise

Ключевое здесь — не список кодов, а два решения: повторять только то, что имеет смысл повторять, и проверять причину остановки, а не факт ответа.

Цены и точные идентификаторы моделей Claude — на витрине, разбор ключей и цен — в статье про Claude API.

FAQ

Что означает ошибка 529 у Claude API?

overloaded_error — сервис перегружен запросами. Это не ваш лимит и не проблема вашего кода: в пиковые часы мощности вендора кончаются. Помогает повтор с нарастающей задержкой, а если задача терпит — переключение на другую модель.

Почему Claude API возвращает 401, хотя ключ правильный?

Чаще всего в ключ попал лишний пробел или перенос строки при копировании, либо переменная окружения не долетела до процесса. Реже — ключ пересоздан, а в конфиге остался старый, или он подставлен не в тот заголовок: у Anthropic напрямую это x-api-key, у OpenAI-совместимых шлюзов — Authorization: Bearer.

Как правильно обрабатывать 429?

Смотреть заголовки ответа — в них указано, какой лимит исчерпан и когда сбросится, — и повторять с экспоненциальной задержкой обязательно с джиттером. Без джиттера параллельные воркеры синхронно упрутся в тот же лимит. У Anthropic два независимых лимита, по запросам и по токенам в минуту; второй исчерпывается раньше.

Почему ответ Claude обрывается на середине?

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

Что делать, если пришла HTML-страница вместо JSON?

Значит, запрос не дошёл до API — его остановил защитный фильтр по дороге. Коды ошибок из документации в этом случае неприменимы. Чаще всего причина в VPN или в адресе дата-центра: повторите тот же запрос напрямую и сравните результат.

Работает ли Claude Code через сторонний шлюз?

С нашим — пока нет. Claude Code обращается к Anthropic-совместимому /v1/messages, а мы отдаём OpenAI-совместимый /v1/chat/completions. Клиенты, у которых адрес API настраивается и формат OpenAI-совместимый, работают штатно.