Ошибки Claude API: 529 Overloaded, 500, 429 и 400 — как исправить

В тестах всё работало. Потом пришёл трафик — и в логах посыпались 529 Overloaded и редкие 500. Часть этих ошибок чините вы. Часть — на стороне Anthropic, и ваша задача лишь грамотно повторить запрос. Весь фокус в том, чтобы понимать, что есть что: бесконечный ретрай 400 просто жжёт деньги и поднимает вас в три ночи впустую. Этот гид раскладывает каждую ошибку Claude API по нужной полке и даёт рабочий код.

Что значит ошибка 529 Overloaded?

529 означает, что серверы Anthropic временно перегружены и не могут принять ваш запрос прямо сейчас. Дело не в ключе, не в квоте и не в промпте — дело в суммарной нагрузке на платформу в эту конкретную секунду. По документации Anthropic, 529 — это статус «Overloaded», и правильная реакция: отступить и повторить чуть позже.

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

Вот как выглядит ответ:

{
  "type": "error",
  "error": {
    "type": "overloaded_error",
    "message": "Overloaded"
  }
}

Причина → решение для 529:

• Причина: перегрузка платформы целиком, обычно в часы пик или сразу после запуска модели.
• Решение: экспоненциальный бэкофф с джиттером (код ниже), ограничение параллелизма, перенос несрочной работы на ночь или в Batch API.
• Решение на уровне архитектуры: маршрутизация через шлюз с фолбэком между провайдерами и отдельной ёмкостью, чтобы один перегруженный бэкенд не превращался в ваш простой.

Честная оговорка: заголовка, который скажет, когда перегрузка спадёт, нет. В отличие от 429, 529 редко несёт полезный retry-after. Так что расписание бэкоффа — единственный ваш рычаг. Не выбрасывайте джиттер: без него все клиенты мира повторяют запросы в один такт и воссоздают всплеск.

Как исправить ошибку 500 в Claude API?

500 Internal Server Error означает, что на стороне Anthropic что-то сломалось при обработке в целом корректного запроса. Вы ничего не сделали не так, и тот же запрос обычно проходит при повторе. Реакция как с 529: отступить и попробовать снова.

Разница — в природе. 500 — это неожиданный сбой, а 529 — ожидаемый сброс нагрузки. С точки зрения кода они обрабатываются одинаково: обе — повторяемые серверные ошибки. Чего делать не надо — разбирать тело ошибки в поисках подсказок и менять запрос. Менять нечего.

{
  "type": "error",
  "error": {
    "type": "api_error",
    "message": "Internal server error"
  }
}

Если 500 лезут раз за разом в течение нескольких минут — это уже не «временно». Проверьте страницу статуса Anthropic и собственный payload: нет ли чего-то настолько громоздкого, что задевает серверный edge-case (например, гигантских схем инструментов). Но в 99% случаев один ретрай решает вопрос.

А что с 503 Service Unavailable?

503 означает, что сервис временно недоступен или на обслуживании — ещё одно временное, повторяемое состояние. Сценарий тот же, что у 500 и 529: экспоненциальный бэкофф, уважение к retry-after, если он есть, и аккуратный отказ после разумного числа попыток.

Держите эту тройку в голове вместе: 529, 500, 503 = повторять. Причины разные (перегрузка, внутренний сбой, недоступность), а реакция одна. Слой ретраев должен ловить все три одной и той же логикой.

Почему возникает ошибка 429 rate limit?

429 Too Many Requests означает, что вы превысили лимит запросов в минуту, токенов в минуту или дневной бюджет токенов. В отличие от семейства 5xx, эта ошибка — про ваше потребление, и API подсказывает, сколько ждать, в заголовке retry-after.

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "Number of requests has exceeded your per-minute limit."
  }
}

Лечение — снова бэкофф, но с нюансом: читайте retry-after и соблюдайте его, а не угадывайте паузу. В остальном лимиты заслуживают отдельного разбора — тиры, TPM против RPM, очереди, маршрутизация моделей — и всё это подробно в гиде по лимитам Claude API. Если коротко: простые вызовы отправляйте на Haiku, повторяющиеся промпты кэшируйте, а при постоянном упоре в потолок подумайте о пуле лимитов.

Из-за чего появляется ошибка 400 Bad Request?

400 означает, что сам запрос некорректен — API отклонил его ещё до обработки, и повтор того же запроса будет падать каждый раз. Это баг в коде, а не временный сбой. Остановитесь, прочитайте сообщение, почините payload.

Самые частые причины, примерно по убыванию:

Вот 400 из-за забытого max_tokens:

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

И корректный запрос в curl, где всё на месте:

curl https://api.claudexia.tech/v1/messages \
  -H "x-api-key: $CLAUDEXIA_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4.5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Привет, Claude."}
    ]
  }'

Поймали 400 — логируйте полный error.message. Он конкретен и обычно указывает прямо на сломанное поле. Не прячьте его.

Почему ключ возвращает 401 или 403?

401 Unauthorized означает, что ключ отсутствует, повреждён или невалиден. 403 Forbidden означает, что ключ валиден, но не имеет права на то, что вы запросили. Ни одна из ошибок не повторяемая — чините учётные данные или права и идите дальше.

Чек-лист для 401:

• Ключ вообще отправляется? Проверьте заголовок x-api-key (или Authorization: Bearer на OpenAI-совместимом эндпоинте).
• Не подгрузилась ли переменная окружения пустой строкой?
• Не перепутаны ли ключ и base URL? Ключ Anthropic sk-ant-… не пройдёт авторизацию на другом base URL, а ключ Claudexia sk_cdx_… нацелен на https://api.claudexia.tech.
• Пробел или перенос строки, случайно вставленный в ключ? Бывает чаще, чем кажется.

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

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "invalid x-api-key"
  }
}

Что такое ошибка 413 Request Too Large?

413 означает, что payload больше, чем готов принять API — обычно потому, что вы набили контекстное окно или приложили слишком тяжёлые картинки и документы. В исходном виде запрос не повторяемый: его нужно ужать.

Типичные триггеры и решения:

• Переполнение контекста: вы вышли за лимит ввода модели. Подрежьте историю, суммируйте старые ходы, разбейте задачу. Тактики «лёгкого» payload — в посте про экономию на Claude API.
• Огромные изображения или PDF: уменьшайте картинки и делите большие документы перед отправкой.
• Разросшаяся история чата: в цикле диалога обрезайте или суммируйте ранние сообщения, а не добавляйте их бесконечно.

Если вы регулярно упираетесь в лимит размера — это сигнал к редизайну: переходите на ретрив (отправляйте только релевантные фрагменты), а не вываливайте всё в каждый вызов.

Как обрабатывать таймауты и ошибки соединения?

Таймауты (408), оборванные соединения и read timeout — это временные сетевые проблемы, а не отказы API. Они повторяемые и особенно часты на длинных генерациях, где ответ долго стримится обратно.

Важны две вещи. Во-первых, выставьте разумный клиентский таймаут: слишком короткий — оборвёте валидные длинные ответы; слишком длинный — зависшее соединение подвесит воркер. Во-вторых, для длинных ответов предпочитайте стриминг: токены начинают приходить сразу, и вероятность словить таймаут по простою резко падает.

import anthropic

# Щедрый таймаут под длинные генерации; стримим, чтобы не словить таймаут по простою
client = anthropic.Anthropic(timeout=120.0)

with client.messages.stream(
    model="claude-sonnet-4.5",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Напиши длинный отчёт."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Ошибки соединения должны попадать в ту же корзину ретраев, что и 529/500/503. Код ниже их ловит.

Полный справочник по кодам статуса

Держите эту таблицу рядом с обработчиком ошибок. Колонка «Действие» — это вся суть: временное повторяем, остальное чиним.

Экспоненциальный бэкофф с джиттером: ретрай для продакшена

Это тот самый код, который нужен любой интеграции с Claude. Он повторяет временные ошибки (429, 500, 503, 529, таймауты, обрывы), соблюдает retry-after, добавляет джиттер, чтобы клиенты не синхронизировались, и — главное — не повторяет ошибки, которые суть ваш баг (400, 401, 403, 413).

Python:

import anthropic
import time
import random

RETRYABLE_STATUS = {408, 429, 500, 503, 529}

def call_with_retry(
    client: anthropic.Anthropic,
    *,
    max_retries: int = 6,
    base_delay: float = 1.0,
    max_delay: float = 60.0,
    **kwargs,
) -> anthropic.types.Message:
    for attempt in range(max_retries):
        try:
            return client.messages.create(**kwargs)
        except (anthropic.APIConnectionError, anthropic.APITimeoutError):
            if attempt == max_retries - 1:
                raise
            _sleep(base_delay, max_delay, attempt, None)
        except anthropic.APIStatusError as e:
            status = e.status_code
            # Не повторяем клиентские ошибки, которые вы сами создали — чините запрос.
            if status not in RETRYABLE_STATUS or attempt == max_retries - 1:
                raise
            retry_after = e.response.headers.get("retry-after") if e.response else None
            _sleep(base_delay, max_delay, attempt, retry_after)
    raise RuntimeError("unreachable")

def _sleep(base: float, cap: float, attempt: int, retry_after) -> None:
    if retry_after:
        delay = float(retry_after)
    else:
        delay = min(cap, base * (2 ** attempt))
    # Полный джиттер: случайная точка в [0, delay].
    time.sleep(random.uniform(0, delay))

TypeScript:

import Anthropic from "@anthropic-ai/sdk";

const RETRYABLE = new Set([408, 429, 500, 503, 529]);
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

export async function callWithRetry(
  client: Anthropic,
  params: Anthropic.MessageCreateParamsNonStreaming,
  { maxRetries = 6, baseDelay = 1000, maxDelay = 60000 } = {},
): Promise<Anthropic.Message> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await client.messages.create(params);
    } catch (err) {
      const last = attempt === maxRetries - 1;

      if (err instanceof Anthropic.APIConnectionError) {
        if (last) throw err;
      } else if (err instanceof Anthropic.APIError && err.status) {
        // 400/401/403/413 — это ваш баг, пробрасываем сразу.
        if (!RETRYABLE.has(err.status) || last) throw err;
      } else {
        throw err;
      }

      const retryAfter = (err as Anthropic.APIError)?.headers?.["retry-after"];
      const base = retryAfter
        ? parseFloat(retryAfter) * 1000
        : Math.min(maxDelay, baseDelay * 2 ** attempt);
      await sleep(Math.random() * base); // полный джиттер
    }
  }
  throw new Error("unreachable");
}

Пара решений, которые стоит понимать. Полный джиттер (случайное значение в [0, delay]) лучше фиксированных экспоненциальных пауз гасит синхронные ретраи — об этом ещё годы назад писал инженерный блог AWS, и это до сих пор так. Ограничитель max_delay не даёт бэкоффу разрастись до абсурдных пауз. А разделение повторяемых и неповторяемых кодов — ровно то, что не даёт 400 крутиться вечно.

Как шлюз сокращает количество ошибок 529?

Шлюз стоит между приложением и Claude, и хорошие шлюзы держат маршрутизацию по провайдерам с автоматическим фолбэком: когда один бэкенд отдаёт 529 Overloaded, запрос повторяется к запасной ёмкости, а не падает. Вы получаете меньше ошибок перегрузки, не написав собственный слой мультипровайдерного фолбэка.

Claudexia работает именно так. Это шлюз к Claude — Opus, Sonnet, Haiku — без аккаунта Anthropic и без VPN. Поскольку он держит отдельную пуловую ёмкость и обходит перегруженные бэкенды, временные 529, которые иначе ударили бы по вашим пользователям, гасятся выше по стеку. Свой бэкофф всё равно держите (всегда), но шлюз снижает, как часто он срабатывает.

Переключение — это правка в одну строку: те же SDK, те же формы запросов.

import anthropic

# Тот же SDK Anthropic, направленный на шлюз.
client = anthropic.Anthropic(
    api_key="sk_cdx_your_key",
    base_url="https://api.claudexia.tech",
)

response = client.messages.create(
    model="claude-sonnet-4.5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Привет"}],
)

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: "sk_cdx_your_key",
  baseURL: "https://api.claudexia.tech",
});

Есть и OpenAI-совместимый эндпоинт, так что Cursor, Claude Code и OpenCode подключаются без изменений. Оплата — за токены, без подписки: Sonnet и Haiku от $0,33 за 1M токенов, Opus от $0,50 за 1M, по тарифам Anthropic. Платить можно через СБП, российскими картами, криптой (USDT/BTC/ETH) или MTS. Детали — в разделе цены и справочнике API, а региональный разбор — в посте доступ к Claude из России в 2026.

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

Ошибка 529 Overloaded — это моя вина?

Нет. 529 отражает нагрузку на платформу Anthropic, а не проблему с ключом, квотой или запросом. Решение: повтор с экспоненциальным бэкоффом и джиттером, снижение параллелизма на время всплеска и, в идеале, маршрутизация через шлюз с фолбэком на отдельную ёмкость. Это самая частая временная ошибка на прямом API.

Стоит ли повторять ошибку 400 Bad Request?

Никогда. 400 означает, что payload некорректен, поэтому идентичный повтор падает идентично — вы лишь потратите вызовы. Прочитайте error.message: он обычно называет сломанное поле и чините его. Классика — забытый max_tokens, невалидный JSON или сообщения, которые не чередуют user/assistant, начиная с user.

В чём разница между 429 и 529?

429 — это ваш лимит: вы превысили RPM, TPM или дневной бюджет, и в ответе есть retry-after с длительностью паузы. 529 — это перегрузка Anthropic: суммарный спрос на платформу, обычно без retry-after. Обе повторяемые, но 429 решается замедлением или повышением лимитов, а 529 — бэкоффом и фолбэком. Подробно про лимиты — в гиде по лимитам.

Сколько раз повторять перед тем, как сдаться?

Для временных ошибок 5–6 попыток с ограниченным экспоненциальным бэкоффом — разумное значение по умолчанию: хватает переждать короткий всплеск, не подвешивая запрос на минуты. Всегда ограничивайте паузу на попытку (например, 60 секундами) и отдавайте вызывающему понятную ошибку после исчерпания ретраев, чтобы зависший запрос не выдавался за успех.

Почему я получаю 401, хотя ключ вроде правильный?

Обычные подозреваемые: переменная окружения подгрузилась пустой строкой; пробел или перенос строки, вставленный в ключ; не тот заголовок (x-api-key против Authorization: Bearer); или несовпадение ключа и base URL — ключ sk-ant-… не пройдёт авторизацию на не-Anthropic base URL, а ключ sk_cdx_… должен идти на https://api.claudexia.tech. Логируйте длину и префикс ключа (но никогда не значение целиком), чтобы быстро это ловить.

Ошибки неизбежны в любом сетевом API. Шаткую интеграцию от надёжной отличает слой ретраев, который понимает разницу между «подожди и повтори» и «почини свой код». Внедрите хелпер бэкоффа выше, держите под рукой таблицу кодов и пусть шлюз впитывает перегрузки. Готовы начать? Быстрый старт выдаст ключ и рабочий запрос за пару минут — а если застрянете, напишите нам или загляните в Telegram.