К содержимому
Блог

Ошибки Claude API: 529, 500, 429, 400 и 401, что делать

Ошибки Claude API: 529, 500, 429, 400 и 401, что делать

Ошибка 529 overloaded значит, что API Anthropic временно перегружен, а ваш запрос тут ни при чём. Через Relay вы 529 не увидите: перегрузка приходит как 429 pool_exhausted, 502 upstream_error или 503 service_unavailable, и все три можно повторять с паузой. Ошибки 400 и 401 повтором не исправить: причина в запросе или в ключе, и чинить нужно её.

Коротко

  • В справочнике ошибок Relay кода 529 нет. Перегрузка модели приходит как 429 pool_exhausted, 502 upstream_error или 503 service_unavailable, у всех трёх x-should-retry: true.

  • Повторяйте по x-should-retry и Retry-After, с потолком на число попыток и случайной добавкой к паузе. Ошибки 400, 401, 402, 403 и 404 повтор не исправит.

  • Ссылка на /docs/errors в тексте ошибки говорит, что ответил шлюз. Текст без ссылки чаще всего пришёл от самой модели (400, 403, 413, 422), и чинить нужно запрос.

Что значит 529 и почему его нет в ответах Relay?

Anthropic описывает 529 как overloaded_error: API временно перегружен. На странице ошибок вендора сказано, что такое случается при высоком трафике у всех пользователей сразу (по странице на 14 октября 2026 года). От вашего ключа, квоты и промпта это не зависит, и менять запрос бессмысленно.

Relay отвечает собственными кодами. Для клиентов формата Anthropic Messages у обоих кодов 503 тип overloaded_error, у 500, 502 и 504 тип api_error, у всех 429 тип rate_limit_error. Поэтому в обработчике ловите класс ошибки по x-should-retry, а не жёсткую пару «529 и повторить». Такая пара в связке с Relay молча не сработает.

Ошибка может прийти и после ответа 200. Когда поток уже пошёл, статус не изменить, и сбой выглядит как событие error в потоке или как обрыв соединения. Anthropic прямо пишет, что при перегрузке overloaded_error может прийти событием внутри потока. Формат потока разобран в руководстве по streaming.

Какие ошибки повторять, а какие чинить?

Статус и кодЧто случилосьПовторЧто делать
400 invalid_requestзапрос не принят: поле, JSON, роль; тот же код у 405 и 422нетпрочитать param и текст, исправить запрос
401 invalid_api_keyключ не передан, отключён, удалён или набран с ошибкойнетпроверить значение ключа и заголовок
402 insufficient_balance, key_limit_exceededкончились деньги на балансе или в лимите ключанетпополнить баланс или поднять лимит ключа
403 model_not_allowed, user_blocked, request_forbiddenмодель запрещена ключу, аккаунт заблокирован или модель отказалась обработать запроснетнастройки ключа, поддержка, содержимое запроса
404 model_not_foundтакой модели нетнетвзять идентификатор из каталога
408 request_timeoutтело не дошло за отведённое время или модель не успеладаповторить
413 request_too_largeзапрос больше допустимогонетсократить запрос
429 rate_limited, concurrency_limit, pool_exhaustedтемп, число потоков или занятая мощность моделидавыдержать Retry-After
500 internal_errorвнутренняя ошибка шлюзадаповторить, при повторении написать в поддержку с request_id
502 upstream_errorмодель ответила ошибкой или не ответиладавыдержать Retry-After
503 service_unavailableсервис перегружен или перезапускаетсядавыдержать Retry-After
503 model_unavailableмодель сейчас недоступна, в том числе пока для неё нет ценынетвыбрать другую модель или вернуться позже
504 upstream_timeoutмодель не прислала ни байта вовремясо stream: true да, без потока нетвключить поток

Два 503 из таблицы ведут себя по-разному, и это главная причина смотреть на x-should-retry, а не на статус. У model_unavailable заголовок Retry-After есть, но x-should-retry равен false: автоматически такой запрос повторять не нужно. Про 429 отдельно рассказывает статья про ошибку 429 и Retry-After, а виды лимитов разобраны в материале про rate limits. Полный перечень кодов лежит в справочнике ошибок.

Из-за чего бывают 400, 401 и 413?

Эти три ошибки повтор не лечит, и причины у них приземлённые.

400 в Relay приходит, когда тело запроса не разобрать: не JSON, нет поля model, stream не логическое значение, max_tokens вне диапазона от 1 до 16777216. Остальные проверки делает сама модель: порядок ролей, обязательные поля, формат инструментов. В таком случае текст ошибки пришёл от неё, и он обычно называет сломанное поле. Шлюз принимает запрос формата Messages и без max_tokens, но модель может его потребовать, так что при 400 с намёком на это поле добавьте его.

401 получают, когда ключ набран с ошибкой (неверная длина или контрольная сумма), неизвестен, отключён, удалён или просрочен. Сообщение у всех этих случаев одно, Invalid API key: по тексту опечатку от отозванного ключа не отличить. Если ключ не передан вовсе, сообщение другое, оно подсказывает заголовки Authorization: Bearer и x-api-key. Порядок проверки собран в статье про ошибки авторизации по ключу.

413 значит, что запрос больше допустимого для шлюза или модели. Сократите историю диалога, вложения и тела инструментов. Повтор того же запроса даст тот же ответ.

Как повторять, чтобы не усугубить перегрузку?

Алгоритм короткий:

  1. Прочитайте x-should-retry. Если там не true, остановитесь и исправьте причину.

  2. Возьмите паузу из Retry-After. Если заголовка нет, как у 500 и 504, расширяйте паузу с каждой попыткой.

  3. Добавьте случайную часть, чтобы параллельные воркеры не вернулись одновременно.

  4. Ограничьте число попыток и общий срок задачи.

  5. Когда лимиты исчерпаны, покажите пользователю явную ошибку с request_id.

Блок-схема: если x-should-retry равен true, клиент ждёт Retry-After или растущую паузу и повторяет запрос, пока не кончатся попытки или срок, иначе ошибку исправляют без повтора

Тот же алгоритм в коде. Повторяются ответы с x-should-retry: true, ошибки соединения, при которых запрос до шлюза не дошёл, и 503 без этого заголовка, но с Retry-After: такой ответ даёт прокси перед шлюзом, когда сам шлюз недоступен. Параметр budget задаёт общий срок задачи: каждая попытка и каждая пауза тратят остаток, а asyncio.timeout обрывает запрос, который в остаток не уложился. Для asyncio.timeout нужен Python 3.11 или новее.

python
import asyncio
import os
import random
import time

import httpx

URL = "https://relay-llm.ru/v1/chat/completions"
HEADERS = {"Authorization": f"Bearer {os.environ['RELAY_API_KEY']}"}


class RelayError(Exception):
    def __init__(self, response):
        try:
            payload = response.json()
        except ValueError:
            payload = None
        error = payload.get("error") if isinstance(payload, dict) else None
        error = error if isinstance(error, dict) else {}
        self.status = response.status_code
        self.code = error.get("code")
        self.request_id = response.headers.get("x-request-id")
        super().__init__(f"{self.status} {self.code} request_id={self.request_id}")


def should_retry(response):
    flag = response.headers.get("x-should-retry")
    if flag is not None:
        return flag == "true"
    return response.status_code == 503 and "retry-after" in response.headers


def backoff(attempt):
    return random.uniform(0, min(30, 2**attempt))


def pause_after(response, attempt):
    retry_after = response.headers.get("retry-after", "")
    if retry_after.isdigit():
        return int(retry_after) + random.uniform(0, 1)
    return backoff(attempt)


async def ask(client, prompt, attempts=4, budget=90.0):
    deadline = time.monotonic() + budget
    body = {"model": "claude-sonnet-5", "messages": [{"role": "user", "content": prompt}]}
    error = None
    for attempt in range(attempts):
        remaining = deadline - time.monotonic()
        if remaining <= 0:
            break
        try:
            async with asyncio.timeout(remaining):
                response = await client.post(URL, headers=HEADERS, json=body)
        except httpx.ConnectError as exc:
            error, pause = exc, backoff(attempt)
        else:
            if response.is_success:
                return response.json()
            error = RelayError(response)
            if not should_retry(response):
                raise error
            pause = pause_after(response, attempt)
        if attempt == attempts - 1 or deadline - time.monotonic() < pause:
            break
        await asyncio.sleep(pause)
    raise error


async def main():
    async with httpx.AsyncClient(timeout=httpx.Timeout(10.0, read=120.0)) as client:
        answer = await ask(client, "Привет")
        print(answer["choices"][0]["message"]["content"])


if __name__ == "__main__":
    asyncio.run(main())

Таймаут чтения и обрыв по сроку здесь намеренно не повторяются. Повтор после своего таймаута может отправить запрос, который модель уже обрабатывает. По правилам Relay повтор считается самостоятельным запросом, и его стоимость зависит от его собственного исхода. Если шлюз ответил ошибкой до первого байта ответа модели, запрос не списывается. Если шлюз уже отправил запрос модели и не дождался первого байта (upstream_timeout) или вы закрыли соединение после отправки, но до первого байта, у текстовых запросов списывается оценка входа. Пока запрос модели не отправлен, резерв освобождается и списания нет. Отсюда практическое правило: свой таймаут не делайте короче, чем нужно длинному запросу для первого токена.

Если вы ходите в Relay через официальный SDK Anthropic, учтите, что он сам повторяет временные ошибки, по умолчанию дважды, и учитывает retry-after (по странице ошибок Anthropic на 14 октября 2026 года). Своя обёртка на четыре попытки поверх этого даст до двенадцати запросов вместо четырёх. Параметр max_retries позволяет отключить повторы SDK или оставить их единственными.

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

Как быть с таймаутами 408 и 504?

408 значит, что тело запроса не дошло за отведённое время или модель не успела обработать запрос. Его можно повторять. 504 upstream_timeout строже: модель не прислала ни байта вовремя. В запросе со stream: true x-should-retry у него равен true, без потока false. Поэтому длинные ответы запрашивайте потоком, даже если пользователю текст целиком показывается в конце. Тот же совет даёт Anthropic на странице ошибок: для долгих запросов лучше использовать streaming. Как читать такой поток, описано в том же руководстве.

Как проверить обработчик ошибок?

Ветку «не повторять» полезно прогнать заведомо неверным запросом и убедиться, что клиент останавливается с первой попытки. По справочнику ошибок неизвестная модель даёт 404 model_not_found, а неверный ключ 401 invalid_api_key, у обоих x-should-retry: false. Для такой проверки возьмите отдельный тестовый конфиг и не копируйте отсутствующий ID в рабочую команду.

Для 401 подставьте в заголовок заведомо неверное значение. Не гоняйте такие проверки сотнями: адрес, с которого много раз присылали неверные ключи, тоже получает rate_limited.

Как отличить ошибку Relay от ошибки модели?

Смотрите на текст сообщения. К ответам шлюза Relay дописывает ссылку вида /docs/errors#код, и по ней видно, какая строка справочника описывает ошибку. В формате Anthropic отдельного поля code нет, поэтому код виден только в этой ссылке. У ошибок, текст которых пришёл от модели (это бывает у 400, 403, 413 и 422), ссылки нет. Такой текст обычно называет сломанное поле, и лечится он правкой запроса. Правило не охватывает ответ прокси при недоступном шлюзе: у него тоже нет ссылки, но это временный 503.

Идентификатор запроса приходит с ответами шлюза. request_id в теле ошибки совпадает с заголовком x-request-id, его и нужно сохранять в логах и передавать поддержке. У 503 от прокси идентификатора нет, тогда фиксируйте время и адрес запроса. Что именно писать в логи, рассказано в статье про request_id и логи.

Для запросов, дошедших до модели, в журнале запросов кабинета видны статус, маршрут (основной или резервный) и число повторов. Заголовок ответа x-route показывает то же: primary или fallback. Шлюз переходит на резервный маршрут только до того, как модель начала отвечать, и такой запрос оплачивается по цене сработавшего маршрута. Ограничить резерв можно в настройках ключа или заголовком x-fallback-policy: any, not_pricier или off. С off при недоступном основном маршруте запрос получит ошибку, поэтому для задач, где важнее доставить ответ, это значение не подходит. Подробности в разделе про резервные маршруты.

Что менять в Claude Code при перегрузке?

Claude Code повторяет временные сбои до десяти раз с нарастающей паузой, прежде чем показать ошибку (документация Claude Code на 14 октября 2026 года). Поэтому ошибка на экране означает, что повторы уже были. Вручную повторяйте не сразу, а через несколько минут: так советует и сама документация.

Что помогает по документации Claude Code:

  • переключить модель командой /model: вместимость считается отдельно по каждой модели;

  • для фоновых запусков и CI включить CLAUDE_CODE_RETRY_WATCHDOG=1, тогда Claude Code повторяет ошибки мощности без ограничения числа попыток;

  • в скриптах, которым нужно упасть быстро, снизить CLAUDE_CODE_MAX_RETRIES.

Для Relay добавьте одно: если приходит model_unavailable, повторы бесполезны по определению, потому что x-should-retry равен false. Берите другую модель из каталога на странице моделей. Если перегрузка совпала с резервными маршрутами, проверьте в настройках ключа значение fallback_policy.

Придёт ли ошибка 529 в ответе Relay?

Нет. В справочнике ошибок Relay такого кода нет, а перегрузка модели приходит как 429 pool_exhausted, 502 upstream_error или 503 service_unavailable. Ориентируйтесь на x-should-retry и Retry-After, а не на номер статуса.

Виноват ли я в ошибке 502 upstream_error?

Как правило, нет: это ответ о том, что модель вернула ошибку или не ответила. Повторите запрос после паузы из Retry-After. Если ошибка не уходит несколько попыток подряд, напишите в поддержку и приложите request_id, время и код ошибки. Полный ключ присылать не нужно.

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

Я бы взял три или четыре попытки и общий срок задачи. Это выбор автора, а не правило Relay. Чем больше попыток, тем дольше пользователь ждёт и тем сильнее вы нагружаете модель в момент перегрузки.

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

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

Источники

Создать аккаунт

Готовы подключиться?Войдите в консоль, пополните баланс и создайте API-ключ.