Ошибки Claude API: что означает каждый код и что делать

Разбор 401, 400, 429, 500, 529 и overloaded: в чём причина каждой, какие можно повторять, а какие бесполезно, и как отличить свою ошибку от чужой.

Половина времени на отладку интеграции уходит на попытку понять, чья это ошибка. Разберём по кодам.

401, ключ не принят

Ключ неверный, отозван или не передан. Проверьте три вещи по порядку:

Заголовок называется правильно. У Anthropic это x-api-key, у OpenAI-совместимого формата Authorization: Bearer.
Ключ не обрезан при копировании и в нём нет переноса строки.
Переменная окружения реально долетела до процесса, а не осталась в вашем шелле.

Последнее ловит больше всего людей: локально работает, в докере нет.

400, запрос не разобран

Модель тут ни при чём, ошибка в теле запроса. Частые причины:

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

Повторять бессмысленно, надо чинить запрос.

429, лимит

Вы превысили запросы или токены в минуту. Единственная правильная реакция это подождать и повторить с растущей задержкой и джиттером. Про лимиты у нас есть отдельный разбор.

500, ошибка на стороне сервиса

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

529 и overloaded

Сервис перегружен. Отличается от 500 тем, что это временно и почти всегда лечится повтором через несколько секунд.

На агентных сценариях имеет смысл заранее заложить обработку: агент, который падает на первом overloaded, теряет весь контекст задачи.

Как быстро понять, чья ошибка

Простое правило: коды 4xx это вы, коды 5xx это сервис.

Исключение это 429. Формально это вы, но лечится ожиданием, а не правкой кода.

Что писать в лог

Минимум, который экономит часы отладки:

код ответа, имя модели, идентификатор запроса,
размер входа в токенах, первые 200 символов тела ошибки

Идентификатор запроса особенно важен: с ним поддержка находит проблему за минуты, без него разговор превращается в гадание.

Через шлюз

Мы прокидываем ошибки провайдера как есть, ничего не переписывая, поэтому диагностика не меняется. Плюс в кабинете видно статистику по каждому ключу, включая долю неуспешных запросов, а живые цифры по сервису лежат на странице статуса.