Ошибки Claude API: 401, 429, overloaded и переполнение контекста (2026)

Ошибки Claude API делятся на три группы: учётные данные и формат запроса, ограничения частоты и ёмкость сервиса, длина контекста. Порядок разбора: сначала HTTP-код и тип ошибки, затем ID запроса, и только потом промпт. Если переставить порядок, конфигурационная проблема легко принимается за проблему модели.

Статья разбирает четыре класса — 401, 429, 529 overloaded и переполнение контекста — и даёт причины, шаги диагностики и готовый код повторов с задержкой. Модели и цены смотрите на странице цены на модели.

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

1. Сначала код состояния, а не правка промпта

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

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

2. 401: сначала заголовок, потом ключ

401 означает, что подлинность не подтверждена; к балансу и возможностям модели это отношения не имеет. Проверяйте по порядку:

Используется ли x-api-key, а не Authorization: Bearer. У Claude Messages API заголовок аутентификации не Bearer.
Передан ли anthropic-version: 2023-06-01. Отсутствие заголовка версии иногда проявляется как 400, но добавить его проще, чем разбираться.
Нет ли пробелов, переводов строк или лишних кавычек вокруг ключа. При копировании из чата это встречается чаще всего.
Действительно ли загружены переменные окружения. Можно смотреть только префикс, не печатайте полный ключ в лог.
Не отозван ли ключ, принадлежит ли он текущей организации или проекту.
Указывает ли Base URL на нужное окружение и используется ли путь /v1/messages.

export ANTHROPIC_API_KEY="sk-ваш-ключ"

curl "https://ai.zhongshangqihang.com/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 64,
    "messages": [{"role": "user", "content": "Ответь только OK"}]
  }'

Ответ 200 означает, что ключ, Base URL и имя модели в порядке. Если 401 сохраняется, проверьте тот же ключ через другой вход — так можно отделить проблему ключа от конфигурации шлюза или сети. Имя модели смотрите на странице цены на модели.

3. 429: лимит — это не «нехватка баланса»

429 означает превышение скорости или квоты. Типичные сценарии:

Превышено число запросов или токенов в минуту.
Резко вырос параллелизм и на короткое время исчерпал квоту.
Несколько сервисов используют один ключ и вытесняют друг друга.
Повторы без задержки: чем больше ошибок, тем больше запросов — «шторм повторов».
Длинный вывод занимает много выходных токенов и оставляет меньше места для параллельных запросов.

Симптом	Возможная причина	Что делать
429 сосредоточены в пиковые часы	Импульс трафика	Очередь и сглаживание отправки
429 при одном ключе на несколько сервисов	Общая квота	Разделить ключи по проектам
После повторов стало хуже	Повторы без задержки	Экспоненциальная задержка с разбросом
Длинные запросы получают 429 первыми	Высокий расход выходных токенов	Снизить max_tokens или параллелизм

Сначала посмотрите на retry-after в ответе, если он есть, и только затем решайте, сколько ждать. SDK различает RateLimitError и обычный APIStatusError; определяйте по типу, а не по строковому совпадению сообщения.

import random
import time
from anthropic import Anthropic, APIStatusError, RateLimitError

client = Anthropic()

def ask(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.messages.create(
                model="claude-sonnet-5-5",
                max_tokens=1024,
                messages=[{"role": "user", "content": prompt}],
            )
            return resp.content[0].text
        except RateLimitError:
            wait = min(2 ** attempt, 20) + random.random()
            print(f"429, попытка {attempt + 1}, ожидание {wait:.1f}s")
            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}s")
                time.sleep(wait)
                continue
            raise
    raise RuntimeError("Лимит повторов исчерпан")

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

4. 529 overloaded: перегрузка сервера, а не ваша квота

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

Убедитесь, что тип ошибки — overloaded_error, не принимайте её за недействительный ключ.
Сохраните request-id и время, чтобы поставщик мог локализовать проблему.
Используйте экспоненциальную задержку со случайным разбросом и ограничение числа попыток, не повторяйте с фиксированным интервалом.
Снизьте параллелизм, сгладьте пик, при необходимости временно отключите некритичные задачи.
Подготовьте резервную модель или канал, но бизнес должен допускать изменение качества вывода.
Если проблема длится дольше ожидаемого, обратитесь к поставщику с ID запроса.

Повтор каждую секунду превращает небольшой сбой в лавину. У стратегии повторов должны быть предел и оповещение, а не бесконечный цикл.

5. Переполнение контекста: сначала измерьте, потом разбивайте

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

Типичные источники: история сообщений не обрезается, инструмент вернул целый лог, документ подан целиком, слишком много изображений, слишком длинный system prompt. Порядок действий:

До запроса измерьте ввод через count_tokens, не угадывайте по числу символов.
Обрежьте самую раннюю историю, оставьте system, последние несколько реплик и резюме.
Для документов сначала извлеките релевантные фрагменты поиском, не вставляйте всю базу.
Длинный документ разбейте по главам, обработайте по частям и объедините результат.
Сжимайте вывод инструментов: возвращайте только нужные поля, не тащите полный ответ снова и снова.
Оставьте место для вывода. max_tokens — верхняя граница вывода, но ввод и вывод вместе должны помещаться в контекст.

import os
from anthropic import Anthropic

client = Anthropic()
MODEL = "claude-sonnet-5-5"
LIMIT = int(os.environ.get("CONTEXT_BUDGET", "200000"))  # собственный бюджет, не лимит модели

def fit_messages(messages):
    while client.messages.count_tokens(model=MODEL, messages=messages).input_tokens > LIMIT:
        if len(messages) <= 2:
            raise ValueError("Одно сообщение превышает бюджет, документ нужно разбить")
        messages = messages[2:]  # убрать самую раннюю пару user/assistant
    return messages

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

6. Таблица порядка диагностики

Зафиксируйте код состояния, тип ошибки, request-id, имя модели и время.
При 401 и 403 проверьте учётные данные и права; при 404 — путь и имя модели.
При 400 проверьте параметры, длину контекста, формат изображений и размер тела запроса.
При 429 проверьте квоту, параллелизм, общий ключ и шторм повторов.
При 529 смотрите состояние сервиса, снижайте параллелизм и готовьте деградацию.
При 500 сначала повторите с задержкой; если ошибка держится, обратитесь к поставщику с ID запроса.
После каждого инцидента добавляйте мониторинг и оповещения, не ждите сообщений пользователей.

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

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

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

Почему повторы не помогают?

Возможно, нет задержки, слишком высок параллелизм, несколько сервисов используют один ключ или сам запрос возвращает 400. Повторы решают только мгновенные ошибки, но не ошибки параметров и прав.

`prompt is too long` означает поломку модели?

Нет. Это превышение контекстного окна. Сначала измерьте count_tokens, затем обрежьте историю, разбейте документ или сделайте поиск. Не добавляйте новые промпты.

Сколько раз повторять?

Единого числа нет. Задайте предел по допуску бизнеса, например 3–5 попыток; после — деградация или оповещение. Интервал должен расти и содержать случайный разброс, чтобы повторы не шли одновременно.

Как отличить ошибку шлюза от официальной?

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

Что дальше

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