Ошибки Claude Code при подключении API: 401, 404, 429 и тайм-ауты (2026)

При подключении Claude Code к стороннему API большинство ошибок связаны не с моделью, а с конфигурацией, аутентификацией или сетью: только настроили — уже 401, сменили Base URL — получили 404, задача дошла до середины — 429, длинная задача зависла до тайм-аута. Порядок действий: сначала посмотреть код состояния и тип ошибки, затем request-id, и только потом менять промпт. Ниже разобраны 401, 404, 429, переполнение контекста и тайм-ауты, приведены шаги диагностики, список полей для логов и пример кода. Модели и биллинг смотрите на странице тарифов.

Примечание: Claude, Claude Code и Anthropic — товарные знаки соответствующих правообладателей. Типы ошибок и поведение интерфейса могут меняться с версиями; статья описывает распространённые случаи октября 2026 года, окончательно ориентируйтесь на официальную документацию.

1. Сначала уровни: где возникает ошибка

Запрос проходит четыре уровня: клиент, сеть, шлюз и модель у поставщика. Один и тот же 401 может означать неверный ключ или несовпадение заголовка аутентификации; один и тот же 404 — лишний /v1 в пути или несуществующее имя модели. Сначала определите уровень, чтобы не менять настройки в неверном направлении.

Код	Тип ошибки	Частая причина	Что делать
400	invalid_request_error	Параметры, формат, длина контекста или лимит расходов	Изменить запрос или лимит и повторить
401	authentication_error	Ключ отсутствует, неверен, просрочен, заголовок не совпадает	Исправить учётные данные, не повторять
402	billing_error	Проблема с биллингом или платёжными данными	Проверить биллинг
403	permission_error	У ключа нет прав на модель или проект	Проверить права
404	not_found_error	Неверный путь или имя модели	Проверить Base URL и имя модели
413	request_too_large	Тело запроса превышает лимит интерфейса	Разделить запрос
429	rate_limit_error	Частота, параллелизм или лимит расходов	Повторить после паузы
500	api_error	Внутренняя ошибка сервера	Повторить после паузы
504	timeout_error	Тайм-аут обработки	Перейти на стриминг или разбить на части
529	overloaded_error	Перегрузка сервера	Пауза, снижение параллелизма

Сохраняйте request-id из заголовков ответа; в теле ошибки обычно также есть request_id. Для обращения в поддержку один request ID полезнее десяти скриншотов. В логах фиксируйте как минимум время, код состояния, тип ошибки, имя модели и request ID; не записывайте полный ключ и чувствительные данные.

2. 401 и 403: заголовок аутентификации и ключ

401 означает, что идентичность не прошла проверку, и не связан с балансом или возможностями модели. В Claude Code есть две легко путаемые переменные: ANTHROPIC_API_KEY отправляется как X-Api-Key; ANTHROPIC_AUTH_TOKEN отправляется как Authorization: Bearer. Если шлюз принимает только один вариант, использование другого стабильно даёт 401. Сначала уточните требование и не экспортируйте обе переменные одновременно.

Другие частые причины: пробелы, переводы строк, кавычки или полноширинные символы вокруг ключа; ключ удалён, просрочен или принадлежит другому рабочему пространству; Base URL указывает на неверную среду; одновременно заданы подписочный вход и API Key; корпоративная сеть или прокси переписывают заголовок аутентификации.

403 обычно означает проблему прав: ключу не открыта модель, нет доступа к проекту, блокирует белый список IP или политика рабочего пространства. 403 не повторяйте — проверьте авторизацию моделей и политику доступа в консоли.

Быстрая изоляция: тем же ключом и Base URL обратитесь напрямую к /v1/messages. Если прямой запрос проходит, а Claude Code падает — проблема в настройках клиента; если не проходит и напрямую — в ключе, шлюзе или сети.

3. 404: путь Base URL и имя модели

404 бывает двух видов: неверный путь или отсутствующий ресурс. Claude Code использует Anthropic Messages API и обычно настраивает Base URL как корневой адрес, а клиент добавляет /v1/messages. Если Base URL уже содержит /v1, фактический путь может стать /v1/v1/messages.

Проверяйте по порядку:

1. Убедитесь в протоколе: Claude Code использует Anthropic Messages, а не OpenAI Chat Completions.
2. Проверьте, не лишний ли /v1 или, наоборот, не пропущен ли он. Для Claude Code обычно указывают корневой адрес; OpenAI-совместимые клиенты — адрес с /v1.
3. Проверьте завершающий слэш и регистр, чтобы не получить двойной слэш или обрезанный путь.
4. Скопируйте актуальное имя модели со страницы тарифов; псевдонимы шлюза могут отличаться от официальных названий.
5. Проверьте минимальным запросом, исключив прокси и кэш клиента.

Если сообщение model not found, проверяйте имя модели и права; если not_found_error и путь явно неверен — проверяйте Base URL.

4. 429: лимиты, квоты и штурм повторов

429 означает, что запрос превысил лимит частоты, параллелизма или расходов. Частые причины: превышено число запросов или токенов в минуту; несколько сервисов используют один ключ; повторы идут без паузы и создают штурм; достигнут лимит расходов аккаунта или рабочего пространства; резкий рост трафика включает ускоренное ограничение.

Часть 429 из-за лимита расходов не содержит retry-after, и ожидание само по себе не поможет — нужно изменить лимит или пополнить баланс. Сначала смотрите retry-after: если он есть, ждите указанное время; если нет — используйте экспоненциальную задержку со случайным разбросом и задайте максимум повторов. 401, 403, 404 и 400 не повторяйте.

Учитывайте повторы по умолчанию в SDK: официальный SDK Anthropic повторяет запросы при ошибках соединения, 429 и 5xx два раза; если бизнес-логика добавляет ещё один слой, фактические запросы умножаются. Планируйте max_retries вместе с бизнес-повторами.

429 и 529 различаются: при 429 сначала проверяйте свой параллелизм, ключ и квоту; 529 — перегрузка сервера, нужны пауза, снижение параллелизма и проверка состояния сервиса.

5. 400 и 413: переполнение контекста и слишком большой запрос

Переполнение контекста обычно возвращает 400 invalid_request_error, в сообщении появляется prompt is too long. Причина не в поломке модели, а в том, что бюджет входа плюс выхода превышает окно контекста.

Порядок действий:

1. До запроса оцените вход через count_tokens, не угадывайте по числу символов.
2. Обрежьте самую раннюю историю, оставив system, последние несколько раундов и резюме.
3. Для документов сначала извлекайте релевантные фрагменты, не вставляйте всю базу.
4. Длинные документы делите по главам и обрабатывайте частями, затем объединяйте.
5. Сжимайте вывод инструментов, возвращайте только нужные поля.
6. Оставляйте место для выхода. max_tokens задаёт только верхнюю границу выхода и не решает переполнение входа.

413 request_too_large означает слишком большое тело запроса, это не то же самое, что длина контекста. Особенно часто лимит превышают изображения, встроенные в base64; сжимайте картинки, используйте интерфейс загрузки файлов или делите запрос.

400 не всегда связан с контекстом. Неподдерживаемый текущей моделью параметр, недопустимая конфигурация thinking или срабатывание лимита расходов тоже могут давать 400. Читайте type и конкретное поле в сообщении об ошибке.

6. Тайм-ауты и обрывы: стриминг, прокси и SSL

Тайм-аут одного запроса в Claude Code управляется API_TIMEOUT_MS, по умолчанию 600000 миллисекунд, то есть 10 минут. В медленной сети или через прокси значение можно увеличить, но не бесконечно: иначе сбой проявится слишком поздно.

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

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

Проблемы прокси и сертификатов тоже проявляются как тайм-аут: для корпоративного прокси задайте HTTPS_PROXY или HTTP_PROXY; при корпоративной TLS-инспекции нужно доверять соответствующему CA, в Node-клиентах обычно через NODE_EXTRA_CA_CERTS; DNS, IPv6, firewall и MTU также могут дестабилизировать соединение — смена сети или мобильная точка доступа помогают быстро это проверить. Если шлюз медленно отдаёт первый байт, обратите внимание на CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS.

7. Логи и чек-лист для поддержки

При диагностике не ограничивайтесь фразой «была ошибка». Соберите следующее:

1. Время, часовой пояс, длительность.
2. Вывод claude --version и операционная система.
3. Base URL (домен без полного ключа).
4. Имя модели, признак стриминга, длительность запроса и число повторов.
5. HTTP-код, тип ошибки и полное сообщение.
6. request-id — может быть и в заголовках, и в теле ответа.
7. Область влияния: один человек, одна сеть, один проект или вся команда.
8. Минимальное воспроизведение: один curl или минимальный репозиторий; результат того же запроса к официальной точке входа.

Маскировка логов должна быть конкретной: у ключа оставляйте первые и последние четыре символа, промпты и код обрабатывайте по корпоративным правилам.

8. Пример: решать по типу ошибки, повторять ли запрос

Пример ниже повторяет только 429, 5xx и сетевые тайм-ауты; 401 и 404 завершаются сразу, чтобы проблема конфигурации не превратилась в штурм повторов. Base URL и имя модели читаются из переменных окружения.

import os
import random
import time

from anthropic import (
    Anthropic,
    APIConnectionError,
    APIStatusError,
    APITimeoutError,
    AuthenticationError,
    NotFoundError,
    RateLimitError,
)

client = Anthropic(
    base_url=os.environ["ANTHROPIC_BASE_URL"],
    auth_token=os.environ["ANTHROPIC_AUTH_TOKEN"],
)

def ask(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.messages.create(
                model=os.environ["ANTHROPIC_MODEL"],
                max_tokens=512,
                messages=[{"role": "user", "content": prompt}],
            )
            return resp.content[0].text
        except AuthenticationError as exc:
            raise SystemExit(f"401: проверьте ключ и заголовок, request-id={exc.request_id}") from exc
        except NotFoundError as exc:
            raise SystemExit(f"404: проверьте Base URL и имя модели, request-id={exc.request_id}") from exc
        except RateLimitError:
            wait = min(2 ** attempt, 20) + random.random()
            print(f"429: повтор через {wait:.1f} с")
            time.sleep(wait)
        except (APITimeoutError, APIConnectionError):
            wait = min(2 ** attempt, 10) + random.random()
            print(f"Тайм-аут или сбой соединения: повтор через {wait:.1f} с")
            time.sleep(wait)
        except APIStatusError as exc:
            if exc.status_code >= 500:
                wait = min(2 ** attempt, 20) + random.random()
                print(f"{exc.status_code}: повтор через {wait:.1f} с")
                time.sleep(wait)
                continue
            raise
    raise RuntimeError("Повторы исчерпаны, переходим к деградации или алерту")

print(ask("Ответь только OK"))

Если шлюз использует X-Api-Key, а не Bearer, замените auth_token= на api_key= или настройте по документации клиента. В примере явно не задан max_retries, поэтому SDK всё равно повторяет по умолчанию; в production настройте это централизованно.

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

401 всегда означает неверный ключ?

Нет. Несовпадение заголовка аутентификации, неверная среда в Base URL и переписывание заголовка прокси тоже дают 401. Сначала проверьте тот же ключ и Base URL напрямую, затем переменные клиента.

404 сохраняется после смены модели — что делать?

Проверяйте путь Base URL. Claude Code обычно указывает корневой адрес, а клиент добавляет /v1/messages; адрес с /v1 даст двойной /v1. Затем сверьте имя модели со списком шлюза.

После 429 достаточно подождать, и всё восстановится?

Не всегда. Ограничение частоты обычно проходит, но 429 из-за лимита расходов может не содержать retry-after; ожидание не поможет, нужно изменить лимит или пополнить баланс. Сначала смотрите тип ошибки и заголовки.

Потоковый запрос вернул 200 и оборвался — это успех?

Нет. После 200 потоковый ответ может отправить событие ошибки через SSE. Клиент должен разбирать поток событий и подтвердить нормальное завершение; иначе результат помечается как неполный и повторяется или вызывает алерт.

Чем больше повторов, тем стабильнее?

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

Что дальше

Создайте тестовый ключ в ZSQH AI Gateway, отработайте 401, 404, 429 и тайм-аут по одному разу, затем подключайте production-мониторинг. Доступность моделей и биллинг смотрите на странице тарифов.

Читайте также:

• Настройка Claude Code с собственным API
• API Key для Claude Code: переменные и защита
• Обзор решений для API-релея

Примечание: Claude, Claude Code и Anthropic — товарные знаки соответствующих правообладателей. Типы ошибок и поведение интерфейса могут меняться; ориентируйтесь на официальную документацию.