Половину времени на отладку интеграции съедает вопрос, на чьей стороне сбой. Пройдёмся по кодам.
401: ключ не принят
Ключ неверный, отозван или вообще не передан. Проверьте по порядку:
- Имя заголовка. У Anthropic это
x-api-key, у OpenAI-совместимого форматаAuthorization: Bearer. - Целостность ключа. При копировании его легко обрезать или прихватить перенос строки.
- Переменная окружения. Она должна дойти до процесса, а не остаться в вашем шелле.
Третий пункт подводит чаще всех: локально всё работает, в Docker нет.
400: запрос не разобран
Дело не в модели, а в теле запроса. Типичные причины:
- имя модели неизвестно, например модель уже отключена
max_tokensвыше предела, который модель поддерживает- роли сообщений чередуются неправильно
- массив сообщений пуст
Повтор не поможет. Чините сам запрос.
429: превышен лимит
Вы упёрлись в лимит запросов или токенов в минуту. Правильная реакция одна: подождать и повторить, увеличивая паузу и добавляя джиттер. Про лимиты мы написали отдельный разбор.
500: сбой на стороне сервиса
Это не ваш баг. Повторять можно и нужно, только с паузой. Но если сбой стабильно воспроизводится на одном и том же запросе, вероятнее всего виноват вход: слишком длинный контекст или битая кодировка.
529 и overloaded
Сервис перегружен. От 500 это отличается тем, что состояние временное: повтор через несколько секунд почти всегда проходит.
В агентных сценариях обработку лучше предусмотреть заранее. Агент, который падает на первом overloaded, теряет весь контекст задачи.
Как быстро понять, чья это ошибка
Грубое правило: коды 4xx указывают на вас, коды 5xx на сервис.
Исключение 429: формально ошибка ваша, но лечат её ожиданием, а не правкой кода.
Что писать в лог
Минимальный набор, который экономит часы:
код ответа, имя модели, идентификатор запроса,
размер входа в токенах, первые 200 символов тела ошибки
Идентификатор запроса важнее всего: по нему поддержка находит проблему за минуты, а без него остаётся только гадать.
Если вы работаете через шлюз
Ошибки провайдера приходят от нас без изменений, поэтому диагностика остаётся прежней. Кроме того, кабинет показывает статистику по каждому ключу, в том числе долю неуспешных запросов, а живые цифры по сервису ищите на странице статуса.