529 Overloaded в Claude API: ретраи, 500, 429 и таймауты

В тестах всё работало. Потом пришёл трафик, и логи заполнились 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: нет ли в нём чего-то настолько громоздкого, что задевает пограничный случай на сервере (например, гигантских схем инструментов). Но в 99% случаев хватает одного повтора.

Что значит 503 Service Unavailable

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

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

Откуда берётся ошибка 429 rate limit

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

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

Если retry-after пришёл, соблюдайте его. Считайте расход токенов, кэшируйте повторяющийся контекст там, где это поддерживается, и ограничивайте частоту запросов на стороне клиента. Доступ через шлюз независимых квот не создаёт. Очереди и работу с квотами провайдера мы разобрали в гиде по лимитам Claude API.

Haiku в каталоге тоже есть: claude-haiku-5.5 и claude-haiku-4.5, цены смотрите на странице моделей. Они работают в канале Premium, в канале Cheap 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.codexkey.ru/v1/messages \
  -H "x-api-key: $CODEXKEY_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-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, а ключ codexkey sk_cdx_… нацелен на https://api.codexkey.ru.
• Не затесался ли в ключ пробел или перенос строки? Случается чаще, чем думают.

При 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-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

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

В codexkey для ключа можно выбрать Premium или Cheap и разрешить резервный Premium для Cheap по правилам провайдера. Перед отправкой трафика проверьте доступность модели и канала. Доступность и политики провайдера продолжают действовать: настройки ключа не дают отдельного пула ёмкости, автоматической смены маршрута и не подавляют upstream-ошибки 529. Эти сбои обрабатывает клиент.

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

import anthropic

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

response = client.messages.create(
    model="claude-sonnet-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.codexkey.ru",
});

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

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

Моя ли вина в ошибке 529 Overloaded?

Нет. Ошибка Anthropic 529 означает перегрузку у провайдера, а не плохой запрос. Ограничивайте повторы в клиенте, используйте бэкофф с джиттером и снижайте параллелизм на время всплеска. Шлюз не гарантирует запасную ёмкость и не подавляет ошибку, так что после исчерпания повторов возвращайте явный отказ.

Нужно ли повторять запрос после 400 Bad Request?

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

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

429 касается квот провайдера: соблюдайте retry-after, если он есть, и снижайте нагрузку со стороны клиента. 529 у Anthropic означает перегрузку платформы. На временные сбои отвечайте ограниченными повторами с бэкоффом, а если сбой не проходит, возвращайте ошибку. Шлюз не гарантирует переключения на другой пул ёмкости. Управление на стороне клиента описано в гиде по лимитам.

Сколько попыток делать, прежде чем сдаться?

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

Откуда 401, если ключ выглядит правильным?

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

Ограничивайте повторы в клиенте и отличайте временные сбои провайдера от некорректных запросов. Проверяйте доступность модели и канала: шлюз не гарантирует, что ошибки перегрузки исчезнут. Начните с быстрого старта. Если нужна помощь с интеграцией, напишите нам или в Telegram: https://t.me/codex_key.