Ошибка 500 в Claude API: повторы, request_id и обращение в поддержку

HTTP 500 с типом api_error от прямого Claude API означает неожиданную внутреннюю ошибку систем Anthropic. Сохраните ответ и идентификатор запроса, проверьте Claude Status и повторяйте безопасную операцию с увеличением паузы и ограничением числа попыток. Если ошибка сохраняется, остановите немедленные повторы: верните приложению окончательный результат, отложите задачу либо обратитесь в поддержку с данными запросов. Такой порядок следует из официального справочника API.

Замена ключа, пополнение баланса и создание новой сессии не являются первым исправлением подтверждённого 500 api_error. Этот код сам по себе не указывает на проблему авторизации или содержимого запроса. А если API Error: 500 показан в терминале Claude Code, используйте порядок восстановления сессии и проверки выполненных действий: настройки его повторов отличаются от собственного API-клиента.

Что сохранить из ответа 500

Запишите HTTP-код, error.type, error.message, время ошибки с часовым поясом и адрес сервиса. Для прямого API особенно важен request_id из JSON либо request-id из заголовков: этот идентификатор позволяет поддержке найти конкретный запрос. В обычном ответе они обозначают один и тот же вызов. Источник: формат ошибок и request ID.

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

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

В Python SDK неуспешный HTTP-ответ приходит как anthropic.APIStatusError или его подкласс. Для обработки точного 500 проверяйте status_code == 500, а не только имя InternalServerError: класс может охватывать и другие серверные статусы. Поля status_code и response документированы в справочнике Python SDK. Поле _request_id относится к полученному объекту успешного ответа; при исключении ищите ID в доступных полях исключения, заголовках и теле ответа.

Отсутствие request ID не доказывает отсутствие HTTP-ответа. Заголовок мог не попасть в журнал, его мог убрать шлюз, а обёртка SDK могла скрыть часть данных. Если есть HTTP-код и тело, сохраните их и продолжайте разбирать этот ответ. Если HTTP-ответа действительно нет, проверьте ошибку соединения или тайм-аут клиента; подтверждённого API 500 в таком случае ещё нет.

Проверьте также, кто вернул ошибку. HTTP 500 с HTML от собственного прокси — ещё не ответ Anthropic api_error. Нужны журналы прокси и, если доступен, исходный ответ поставщика. Когда место сбоя неясно, поможет разбор внутренней ошибки в чате, Code, API и шлюзе.

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

Официальный Python SDK по умолчанию допускает два повтора временного сбоя с короткой экспоненциальной задержкой. Вместе с первоначальным запросом это до трёх HTTP-попыток, если политика разрешает каждую из них. К повторяемым относятся ошибки соединения, 408, 409, 429 и статусы от 500. Параметр max_retries задаётся на клиенте или для отдельного вызова через with_options; max_retries=0 отключает повторы SDK. Источник: повторы Python SDK.

Выберите, кто управляет повторными попытками:

• Для простой интеграции оставьте ограниченные повторы SDK и обработайте окончательное исключение. После него не запускайте ещё один немедленный цикл.
• Если повторными попытками управляет очередь или приложение, отключите повторы SDK и задайте собственные условия ожидания, прекращения и повторной постановки задачи.

Это предотвращает незаметное умножение запросов. Например, три внешних вызова SDK с двумя разрешёнными повторами каждый могут дать 3 × (1 + 2) = 9 HTTP-попыток, ещё до повторов шлюза. Это расчёт для указанных настроек, а не измерение вашего приложения; успех или запрет повтора остановит цепочку раньше.

Сервер может передать retry-after. В исходниках Python SDK на ветке main, прочитанных 4 октября 2026 года, также учитывается явный запрет x-should-retry: false. Поведение проверяйте для установленной версии: код main не доказывает, что она уже содержит ту же реализацию. Не сокращайте указанное сервером ожидание ради ещё одной быстрой попытки; если оно не подходит сроку задачи, отложите работу. Источник: реализация повторов SDK.

Пример: обработать окончательный 500 и вернуть решение приложению

Следующая функция предназначена для обычного непотокового вызова без инструментов. Передайте уже настроенный anthropic.Anthropic, доступный вам идентификатор модели и список сообщений. Функция разрешает SDK два повтора и возвращает отдельные результаты для успеха, окончательного 500, другого HTTP-статуса и ошибки без ответа. Внешних действий и автоматической постановки в очередь здесь нет.

import anthropic


def create_message(client, model, messages):
    try:
        message = client.with_options(
            max_retries=2,
            timeout=20.0,
        ).messages.create(
            model=model,
            max_tokens=256,
            messages=messages,
        )
        return {
            "result": "ok",
            "message": message,
            "request_id": getattr(message, "_request_id", None),
        }
    except anthropic.APIStatusError as exc:
        try:
            body = exc.response.json()
        except ValueError:
            body = {}
        if not isinstance(body, dict):
            body = {}
        error = body.get("error")
        if not isinstance(error, dict):
            error = {}
        request_id = (
            getattr(exc, "request_id", None)
            or exc.response.headers.get("request-id")
            or body.get("request_id")
        )
        return {
            "result": "defer" if exc.status_code == 500 else "http_error",
            "status_code": exc.status_code,
            "error_type": error.get("type"),
            "request_id": request_id,
            "model": model,
        }
    except anthropic.APITimeoutError:
        return {"result": "timeout", "model": model}
    except anthropic.APIConnectionError:
        return {"result": "connection_error", "model": model}

defer означает, что 500 дошёл до вызывающего кода после применимых повторов SDK. Для интерактивного запроса обработайте этот результат явным сообщением: «Сервис временно недоступен; ответ не получен». Для фоновой задачи сохраните её состояние и назначьте более позднюю попытку в своей очереди, если задача остаётся актуальной и повтор безопасен. Само возвращаемое слово defer не создаёт задание в очереди.

http_error требует разбора фактического кода и типа ошибки. Например, 529 overloaded_error ведёт к снижению нагрузки и настройке повторов при перегрузке; 401 authentication_error — к проверке ключа. Не превращайте каждый статус в одинаковый повтор 500. Типы ошибок различаются в официальной таблице API.

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

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

Почему timeout не задаёт общий срок задачи

timeout=20.0 в примере меняет тайм-аут запроса; это не обещание завершить всю функцию за 20 секунд. Есть время отдельных попыток, задержки между ними и возможное ожидание, указанное сервером. По умолчанию Python SDK использует тайм-аут 10 минут, а ошибки тайм-аута тоже допускают два повтора. Источник: тайм-ауты Python SDK.

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

Что делать, если 500 повторяется

Сначала проверьте текущую страницу статуса Claude и запишите время проверки. Опубликованный инцидент помогает выбрать паузу и сообщить пользователю о задержке. Зелёный статус не устанавливает причину отдельного сбоя и не подтверждает здоровье вашего шлюза или конкретной модели.

Для первоначального ограниченного повтора сохраните модель, адрес API и форму запроса. Так результат показывает, восстановился ли тот же вызов. Если меняете модель или сервис, запишите это как обходной путь и учитывайте отличия ответа; успех после нескольких одновременных изменений не объясняет исходный 500.

После исчерпания выбранных попыток у задачи должен быть один из понятных исходов:

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

Для операции с публикацией, записью в базу или другими внешними действиями храните собственный идентификатор задачи и проверяйте фактический результат перед повторным запуском. Он связывает бизнес-операцию, тогда как новый request_id обозначает конкретную попытку обращения к API. Сам по себе такой идентификатор не обеспечивает защиту от дублей: её должно реализовать приложение. Не предполагайте, что произвольный заголовок Idempotency-Key автоматически отменяет повторные действия.

Какие данные отправить в поддержку

При постоянном 500 api_error Anthropic рекомендует обращаться в поддержку с идентификатором запроса. Источник: обработка 500. Соберите короткое описание, по которому можно найти вызов и понять его условия:

• Время первой и последней ошибки, часовой пояс, HTTP-код, error.type и сообщение.
• Доступные request-id или request_id; при их отсутствии — явно указать, что идентификатор не получен.
• Модель, адрес API, потоковый или обычный режим, версия SDK и способ подключения: напрямую либо через конкретный шлюз.
• Число фактически известных попыток, настройки повторов SDK, очереди и шлюза, задержки и конечный результат. Не выдавать разрешённое число повторов за измеренное.
• Минимальный корректный пример запроса с удалёнными секретами и персональными данными, а также влияние сбоя на работу приложения.

Если ошибка создана вашим шлюзом, начните с его оператора и сохраните оба доступных идентификатора — шлюза и поставщика. При прямом ответе Anthropic нужен её request ID. Не прикладывайте ключи, токены, cookie, приватные сообщения пользователей и полный дамп окружения. Удаление чувствительных данных не должно менять структуру запроса так, что пример перестанет быть пригодным для диагностики.

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

500 api_error означает, что закончился лимит?

Нет. В справочнике прямого Claude API 500 обозначает неожиданную внутреннюю ошибку. Ограничения скорости и некоторые пределы расходов относятся к 429; перегрузка — к 529. Действия определяются реальным кодом и телом ответа, а не общей надписью Internal Server Error. Источник: HTTP-ошибки API.

Через сколько минут исчезнет внутренняя ошибка сервера?

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

Нужно ли менять API-ключ после 500?

Подтверждённый 500 сам по себе не даёт такого основания. Проверяйте ключ при отдельном сигнале авторизации, например 401 authentication_error, либо при известной утечке. Пересоздание ключа не исправляет внутреннюю ошибку сервиса. Источник: классификация API.

Что делать, если поток оборвался после HTTP 200?

Проверьте завершение потока и сохраните уже полученный результат. При SSE ошибка может возникнуть после начального HTTP 200, поэтому обычного обработчика HTTP-статусов недостаточно. Перед повтором выясните, какие части ответа и внешние действия уже завершились; не дописывайте повторный полный ответ к старому как будто это продолжение. Источник: ошибки потоковых ответов.