Ошибки Claude API: какие коды повторять, а какие исправлять

Ошибка Claude API отвечает на один вопрос: повторить запрос или исправить его. Повторять имеет смысл 429 с заголовком retry-after, 500, 504, 529 и обрыв стрима. Остальные коды 4xx не пройдут, пока вы не исправите запрос, ключ или баланс. Схему ломают два случая: 429 без retry-after, после которого ретраи бесполезны до первого числа месяца, и ответ 200 с оборванным или пустым текстом.

Чей это ответ: JSON или HTML

Начните с тела ответа. API Anthropic всегда возвращает ошибку в JSON: объект error с полями type и message, а рядом request_id (Anthropic).

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "The requested resource could not be found."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

Тот же идентификатор приходит в заголовке request-id, а в Python SDK он доступен как message._request_id. Поддержка Anthropic просит именно его, поэтому пишите его в лог вместе с кодом.

Если вместо JSON пришла HTML-страница, до API запрос не дошёл: его остановил сетевой фильтр или прокси по дороге, и коды из этой статьи к нему не относятся. Учтите и то, что 413 на слишком большом запросе Anthropic возвращает на уровне Cloudflare, ещё до серверов API. Почему из России так отвечают фильтры и почему VPN тут не лекарство, разобрано отдельно.

Через OpenAI-совместимый шлюз конверт другой: ошибка приходит в формате OpenAI, с полями message, type и code, и набор кодов отличается. Об этом отдельный раздел ниже.

Коды Anthropic: что повторять, что исправлять

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

Если ваш код тоже повторяет запросы, попытки перемножаются. Пять ваших попыток, внутри каждой из которых SDK делает ещё две, дают 15 запросов на одну ошибку, и при 429 это только продлевает блокировку.

400: что говорит текст сообщения

Под кодом 400 у Claude скрываются слишком разные причины, поэтому читайте error.message. Тексты ниже взяты из документации Anthropic на 29.10.2026.

Источники: справочник ошибок, окно контекста, лимиты, аутентификация. Сообщение о пустом балансе приходит с кодом 400, а не 402, это видно по issue в SDK Anthropic.

Ещё один источник 400 — temperature, top_p и top_k. На Claude 4.7 и новее их принимают только со значением по умолчанию, а в версии API 2026-10-21 они отклоняются на любой модели (Anthropic). Как переносить такие параметры из кода под GPT, разобрано в статье Claude API из кода.

429: какой именно лимит кончился

Лимиты Anthropic считаются на организацию и класс модели в трёх величинах: запросы в минуту (RPM), входные токены в минуту (ITPM) и выходные (OTPM) (Anthropic). Ответ 429 называет, какой из них превышен. Заголовки anthropic-ratelimit-* в каждом ответе показывают остаток заранее, до того как лимит кончится.

Токенный лимит обычно кончается первым. На стартовом тире у Sonnet 5.5 лимит 1 000 запросов и 2 000 000 входных токенов в минуту, то есть в среднем 2 000 токенов на запрос. Агент, который отправляет по 20 000 токенов контекста, упрётся в ITPM на сотом запросе в минуту, использовав 10% нормы по запросам. У Fable 5 и 5.1 на том же тире общий ITPM равен 500 000, и равновесие наступает уже на 500 токенах.

Два свойства лимитов неочевидны. Ёмкость пополняется непрерывно, по алгоритму token bucket, поэтому норма 60 запросов в минуту может применяться как один запрос в секунду, и короткий всплеск даёт 429 при недобранной минутной норме. Зато токены, прочитанные из кэша, у текущих моделей Claude в ITPM не входят, и кэширование повторяющегося контекста поднимает пропускную способность без смены тира.

429 без заголовка retry-after означает другое: организация упёрлась в месячный потолок трат своего тира, $500 на Start или $1 000 на Build. В теле будет error.details.error_code со значением enforced_spend_limit_reached и дата возврата доступа — 00:00 UTC первого числа следующего месяца. Ретраи, в том числе встроенные в SDK, до этого момента бесполезны, помогает только переход на следующий тир. Ещё 429 бывает из-за лимитов ускорения при резком росте трафика, и Anthropic советует наращивать нагрузку плавно.

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

529, 500 и обрыв стрима: проблема на стороне Anthropic

529 overloaded_error значит, что API перегружен запросами всех пользователей, а не вашими. 500 — внутренняя ошибка Anthropic, 504 — запрос не уложился во время. Все три повторяют с нарастающей паузой. Если 500 держится на одном и том же запросе, Anthropic просит написать в поддержку с request_id. Состояние сервиса видно на status.claude.com, где Claude API, Console и Claude Code показаны отдельно.

В стриме ошибка может прийти после ответа 200, когда заголовки уже отправлены. Тогда вместо кода HTTP в потоке появляется событие (Anthropic):

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

Обработчик, который смотрит только на статус ответа, такую ошибку пропустит.

504 и оборванные соединения часто связаны с длительностью запроса. Anthropic советует запросы дольше 10 минут отправлять через стриминг или Batch API, а SDK не даст отправить без стриминга запрос, который рискует не уложиться в 10 минут. Большой max_tokens без стриминга опасен ещё и тем, что некоторые сети рвут простаивающие соединения (Anthropic).

Ответ 200, а текста нет или он оборван

Самая неприятная ошибка приходит без кода. Ответ 200, а что случилось, написано в поле stop_reason — причине остановки (Anthropic):

• max_tokens: ответ упёрся в ваш потолок. На моделях с размышлением черновик тратит тот же лимит, поэтому короткий ответ может оборваться после длинного черновика. Если обрезан вызов инструмента, повторите запрос с большим max_tokens.
• model_context_window_exceeded: ответ заполнил окно контекста. На Claude 4.5 и новее API принимает запрос, даже если вход плюс max_tokens больше окна, и останавливает генерацию, когда место кончилось.
• refusal: модель отказалась отвечать, категория политики указана в stop_details.
• end_turn с пустым ответом в 2–3 токена: обычно так бывает после результатов инструментов, если к ним в том же сообщении добавлен текст. Повтор того же запроса не поможет: уберите лишний текст или добавьте новое сообщение с просьбой продолжить.
• pause_turn: серверный инструмент дошёл до лимита итераций, и ход надо продолжить следующим запросом.

В формате OpenAI то же поле называется finish_reason, и обрыв по потолку выглядит как length. Проверяйте причину остановки в каждом ответе, а не только наличие текста.

Те же ошибки через OpenAI-совместимый шлюз

Шлюз переводит ответ Anthropic в конверт OpenAI и добавляет свои коды. У altrouter они такие (справочник ошибок):

• 402 с кодом insufficient_quota — на балансе не хватает денег, с кодом spend_limit_exceeded — ключ упёрся в свой потолок трат. У Anthropic в похожих ситуациях приходит 400.
• 429 — лимит вашего ключа: по умолчанию 600 запросов в минуту в фиксированном окне 60 секунд, с Retry-After: 60 (лимиты). 429 от провайдера до клиента не доходит: запрос уходит на резервный маршрут.
• Сбои провайдера приходят как 502, 503 или 504, кода 529 в этом списке нет. 502 — провайдер ответил ошибкой, 503 — живого маршрута не нашлось и резервные уже перебраны, 504 — запрос не уложился во время (надёжность). У модели с единственным провайдером резерва нет, и это наш минус.
• 400, если max_tokens больше потолка вывода модели: Claude проверяет его строго (параметры).
• 404 model_not_found — такого id нет в каталоге. Сверяйте id с GET /v1/models: у нас версия пишется через точку, claude-sonnet-5.5.

Обрыв уже начатого стрима HTTP-кода не имеет и виден в журнале запросов как stream_error. Резерв денег под неудачный запрос освобождается автоматически, баланс он не тратит.

Обработчик, который повторяет только то, что имеет смысл

Каркас для OpenAI SDK и шлюза. Встроенные повторы SDK здесь выключены, чтобы попытки не перемножались.

import os
import random
import time

import openai
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ALTROUTER_API_KEY"],
    base_url="https://api.altrouter.ai/v1",
    max_retries=0,  # повторяем сами, иначе SDK добавит свои две попытки
)

RETRY = {429, 500, 502, 503, 504}


def ask(messages, model="claude-sonnet-5.5", tries=5):
    for attempt in range(tries):
        try:
            resp = client.chat.completions.create(
                model=model, messages=messages, max_tokens=4000,
            )
        except openai.APIStatusError as e:
            if e.status_code not in RETRY or attempt == tries - 1:
                raise  # 400, 401, 402, 403, 404: исправить запрос, ключ или баланс
            wait = e.response.headers.get("retry-after")
            time.sleep(float(wait) if wait else 2 ** attempt + random.random())
            continue
        except openai.APIConnectionError:
            if attempt == tries - 1:
                raise
            time.sleep(2 ** attempt + random.random())
            continue

        choice = resp.choices[0]
        if choice.finish_reason == "length":
            raise RuntimeError("ответ обрезан по max_tokens: поднимите лимит или сократите задачу")
        return choice.message.content

Повтор по умолчанию в OpenAI SDK срабатывает на сетевые сбои, 408, 409, 429 и все 5xx (README openai-python), поэтому max_retries=0 здесь обязателен. В SDK Anthropic логика та же: исключение anthropic.APIStatusError с полем status_code. При прямой работе с Anthropic добавьте проверку enforced_spend_limit_reached, чтобы не повторять 429 месячного потолка, и 529 в список повторяемых кодов.

FAQ