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

> Если Claude API вернул 500 api_error, сохраните request_id и разрешите ограниченные повторы с увеличением паузы. При постоянном сбое завершите запрос с понятной ошибкой или отложите задачу, сохранив данные для поддержки.

- URL: https://blog.laozhang.ai/ru/posts/claude-api-internal-server-error
- Published: 2026-05-02
- Updated: 2026-10-05
- Author: LaoZhang AI Team (https://blog.laozhang.ai/ru/about)
- Topic: Claude и Anthropic
- Tags: Claude API, API Error 500, api_error, Internal Server Error, Anthropic, Обработка ошибок

---
**HTTP `500` с типом `api_error` от прямого Claude API означает неожиданную внутреннюю ошибку систем Anthropic.** Сохраните ответ и идентификатор запроса, проверьте [Claude Status](https://status.claude.com/) и повторяйте безопасную операцию с увеличением паузы и ограничением числа попыток. Если ошибка сохраняется, остановите немедленные повторы: верните приложению окончательный результат, отложите задачу либо обратитесь в поддержку с данными запросов. Такой порядок следует из [официального справочника API](https://platform.claude.com/docs/en/api/errors).

Замена ключа, пополнение баланса и создание новой сессии не являются первым исправлением подтверждённого `500 api_error`. Этот код сам по себе не указывает на проблему авторизации или содержимого запроса. А если `API Error: 500` показан в терминале Claude Code, используйте [порядок восстановления сессии и проверки выполненных действий](https://blog.laozhang.ai/ru/posts/claude-code-500-529-rate-limit): настройки его повторов отличаются от собственного API-клиента.

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

Запишите HTTP-код, `error.type`, `error.message`, время ошибки с часовым поясом и адрес сервиса. Для прямого API особенно важен `request_id` из JSON либо `request-id` из заголовков: этот идентификатор позволяет поддержке найти конкретный запрос. В обычном ответе они обозначают один и тот же вызов. [Источник: формат ошибок и request ID](https://platform.claude.com/docs/en/api/errors).

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

```json
{
  "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](https://platform.claude.com/docs/en/api/sdks/python#handling-errors). Поле `_request_id` относится к полученному объекту успешного ответа; при исключении ищите ID в доступных полях исключения, заголовках и теле ответа.

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

Проверьте также, кто вернул ошибку. HTTP 500 с HTML от собственного прокси — ещё не ответ Anthropic `api_error`. Нужны журналы прокси и, если доступен, исходный ответ поставщика. Когда место сбоя неясно, поможет [разбор внутренней ошибки в чате, Code, API и шлюзе](https://blog.laozhang.ai/ru/posts/claude-internal-server-error).

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

Официальный Python SDK по умолчанию допускает **два повтора** временного сбоя с короткой экспоненциальной задержкой. Вместе с первоначальным запросом это до трёх HTTP-попыток, если политика разрешает каждую из них. К повторяемым относятся ошибки соединения, 408, 409, 429 и статусы от 500. Параметр `max_retries` задаётся на клиенте или для отдельного вызова через `with_options`; `max_retries=0` отключает повторы SDK. [Источник: повторы Python SDK](https://platform.claude.com/docs/en/api/sdks/python#retries).

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

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

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

Сервер может передать `retry-after`. В исходниках Python SDK на ветке `main`, прочитанных 4 октября 2026 года, также учитывается явный запрет `x-should-retry: false`. Поведение проверяйте для установленной версии: код `main` не доказывает, что она уже содержит ту же реализацию. Не сокращайте указанное сервером ожидание ради ещё одной быстрой попытки; если оно не подходит сроку задачи, отложите работу. [Источник: реализация повторов SDK](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/_base_client.py).

![Один владелец повторов и расчёт числа попыток SDK и внешней очереди](https://blog.laozhang.ai/posts/ru/claude-api-internal-server-error/img/recovery-loop.webp)


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

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

```python
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` ведёт к [снижению нагрузки и настройке повторов при перегрузке](https://blog.laozhang.ai/ru/posts/claude-api-error-529-overloaded); `401 authentication_error` — к проверке ключа. Не превращайте каждый статус в одинаковый повтор 500. Типы ошибок различаются в [официальной таблице API](https://platform.claude.com/docs/en/api/errors).

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

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

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

`timeout=20.0` в примере меняет тайм-аут запроса; это **не обещание завершить всю функцию за 20 секунд**. Есть время отдельных попыток, задержки между ними и возможное ожидание, указанное сервером. По умолчанию Python SDK использует тайм-аут 10 минут, а ошибки тайм-аута тоже допускают два повтора. [Источник: тайм-ауты Python SDK](https://platform.claude.com/docs/en/api/sdks/python#timeouts).

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

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

Сначала проверьте [текущую страницу статуса Claude](https://status.claude.com/) и запишите время проверки. Опубликованный инцидент помогает выбрать паузу и сообщить пользователю о задержке. Зелёный статус не устанавливает причину отдельного сбоя и не подтверждает здоровье вашего шлюза или конкретной модели.

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

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

| Ситуация | Что сделать сейчас | Как продолжить |
| --- | --- | --- |
| Пользователь ждёт ответ в интерфейсе | Завершить ожидание сообщением о недоступности и сохранить исходный запрос в рамках правил приватности | Предложить повтор позже; не показывать пустой ответ как успех |
| Фоновая задача может подождать | Сохранить состояние, идентификатор задачи и следующую допустимую попытку | Возобновить через очередь, если срок и безопасность позволяют |
| Повтор больше не нужен или опасен | Завершить задачу с ошибкой либо передать на ручную проверку | Проверить уже выполненные действия перед новым запуском |
| Один и тот же вызов устойчиво возвращает 500 | Прекратить частые попытки и подготовить обращение в поддержку | Дать поддержке идентификаторы и минимальный воспроизводимый пример |

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

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

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

При постоянном `500 api_error` Anthropic рекомендует обращаться в поддержку с идентификатором запроса. [Источник: обработка 500](https://platform.claude.com/docs/en/api/errors). Соберите короткое описание, по которому можно найти вызов и понять его условия:

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

![Время, код ошибки, request ID и условия вызова для обращения в поддержку](https://blog.laozhang.ai/posts/ru/claude-api-internal-server-error/img/escalation-packet.webp)

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

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

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

Нет. В справочнике прямого Claude API 500 обозначает неожиданную внутреннюю ошибку. Ограничения скорости и некоторые пределы расходов относятся к 429; перегрузка — к 529. Действия определяются реальным кодом и телом ответа, а не общей надписью Internal Server Error. [Источник: HTTP-ошибки API](https://platform.claude.com/docs/en/api/errors).

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

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

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

Подтверждённый 500 сам по себе не даёт такого основания. Проверяйте ключ при отдельном сигнале авторизации, например `401 authentication_error`, либо при известной утечке. Пересоздание ключа не исправляет внутреннюю ошибку сервиса. [Источник: классификация API](https://platform.claude.com/docs/en/api/errors).

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

Проверьте завершение потока и сохраните уже полученный результат. При SSE ошибка может возникнуть после начального HTTP 200, поэтому обычного обработчика HTTP-статусов недостаточно. Перед повтором выясните, какие части ответа и внешние действия уже завершились; не дописывайте повторный полный ответ к старому как будто это продолжение. [Источник: ошибки потоковых ответов](https://platform.claude.com/docs/en/api/errors).

## Источники

Внешние страницы, на которые ссылается это руководство, в порядке упоминания. Последнее обновление: 2026-10-05.

- [Claude Status](https://status.claude.com/) (status.claude.com)
- [официального справочника API](https://platform.claude.com/docs/en/api/errors) (platform.claude.com)
- [справочнике Python SDK](https://platform.claude.com/docs/en/api/sdks/python) (platform.claude.com)
- [Источник: реализация повторов SDK](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/_base_client.py) (github.com)