Claude API error: типы ошибок Anthropic-формата и что с ними делать

Когда Claude API возвращает ошибку, полезно сразу понять одно: это сбой, который пройдёт сам, или запрос, который нужно исправить. Ниже разбор типов ошибок Messages API (формат Anthropic), соответствующие HTTP-коды при работе через шлюз Zukko и готовый обработчик на Python. Если вы искали, что делать, когда «claude api не работает», в конце есть чек-лист из пяти проверок.

Как выглядит ошибка в Anthropic-формате

При вызове POST https://api.zukko.pro/v1/messages ошибка приходит с HTTP-кодом 4xx или 5xx и телом такого вида:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens: field required"
  }
}

Поле error.type задаёт категорию, message объясняет детали. Ориентируйтесь на оба: тип показывает, что делать, а текст говорит, какое поле или параметр виноват.

Типы ошибок

Это типы из документации Anthropic (там же описан редкий conflict_error с кодом 409). Через шлюз к ним добавляются собственные коды Zukko; HTTP-статус остаётся самым надёжным ориентиром.

Коды шлюза и что за ними стоит

Точное значение error.type для кодов вроде 402 или 503 зависит от реализации, поэтому не привязывайте логику к строке типа там, где есть HTTP-статус: проверьте реальный ответ на своём ключе. Пока 529 и 503 в ваших логах выглядят как временные сбои, обрабатывайте их одинаково: пауза и повтор.

Подробно про отдельные случаи: ошибка 401↗ и ошибка 529 overloaded↗.

Что ретраить, а что исправлять

Правило простое. 4xx (кроме части 429) означает, что проблема в вашем запросе или ключе, и повтор вернёт тот же ответ, но спишет время. 5xx и 529 означают временный сбой, и повтор с экспоненциальной паузой оправдан. 429 нужно разбирать: ограничение у провайдера проходит, а исчерпанный лимит ключа (key_daily_limit_reached или key_monthly_limit_reached) нет.

Отдельный случай: стриминг. В потоковом режиме сервер уже ответил 200 и начал отдавать события, поэтому сбой посреди ответа приходит не HTTP-кодом, а событием error внутри потока. Если вы обрабатываете только исключения на создании запроса, такую ошибку можно пропустить.

Обработчик на Python

Официальный Anthropic SDK сам повторяет часть запросов, но разбирать причины всё равно удобнее явно. Обратите внимание: для Anthropic SDK base_url пишется без /v1, SDK добавляет путь сам.

import os
import time
import anthropic

client = anthropic.Anthropic(
    base_url="https://api.zukko.pro",
    api_key=os.environ["ZUKKO_API_KEY"],
    max_retries=0,
)

def ask(prompt: str, attempts: int = 5) -> str:
    for attempt in range(attempts):
        try:
            msg = client.messages.create(

Решение принимается по status_code, а не по классу исключения: набор классов в SDK меняется от версии к версии (например, в свежих версиях для 529 есть отдельный OverloadedError, который не наследуется от InternalServerError), а HTTP-статус стабилен.

Claude API не работает: пять проверок

1. Адрес. Для Anthropic SDK и Claude Code base URL https://api.zukko.pro без /v1; для клиентов на OpenAI-формате https://api.zukko.pro/v1.
2. Ключ и заголовки. Authorization: Bearer fetch_... или x-api-key (SDK шлёт его сам), плюс anthropic-version: 2023-06-01 при прямых вызовах.
3. Имя модели. Сверьте с ответом GET https://api.zukko.pro/v1/models: модели появляются и выключаются.
4. Баланс и лимиты ключа. Баланс и расход видны в кабинете↗, дневной и месячный лимит ключа тоже.
5. Статус провайдера. Если всё выше в порядке, а 5xx идут подряд, проверьте страницу статуса Anthropic и повторите позже или переключитесь на другую модель.

Быстрая проверка из терминала:

curl -i https://api.zukko.pro/v1/messages \
  -H "Authorization: Bearer fetch_ваш_ключ" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5-5","max_tokens":50,"messages":[{"role":"user","content":"ping"}]}'

Флаг -i покажет HTTP-статус и заголовки вместе с телом. Подробности формата запроса есть в справочнике Messages API↗, про ключи и заголовки в разделе авторизации↗.

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

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

overloaded_error (529) означает, что сервис перегружен в целом, вы тут ни при чём. 429 говорит о превышении лимита: вашего ключа или у провайдера. Реакция на оба с паузой, но лимит ключа повтором не лечится.

Почему invalid_request_error возвращается снова и снова?

Потому что запрос неверный, и сервер вернёт то же самое. Прочитайте error.message: часто это отсутствующий max_tokens, неверная структура messages или параметр, который модель не принимает.

Ошибка пришла посреди стриминга. Это нормально?

Да, в потоке ошибка передаётся событием error, потому что HTTP-статус уже был 200. Обрабатывайте такие события и повторяйте запрос целиком.

Где посмотреть, что именно списалось и почему упало?

В кабинете, раздел «Использование», и через API (/usage). Создать отдельный ключ под проект и ограничить его моделями можно в разделе ключей↗.