Ошибки Claude API



Ошибки HTTP

API следует предсказуемому формату HTTP-кодов ошибок:

• 400 - invalid_request_error: Возникла проблема с форматом или содержимым вашего запроса. Этот тип ошибки также может использоваться для других кодов состояния 4XX, не перечисленных в этом разделе.

• 401 - authentication_error: Возникла проблема с вашим ключом API (например, он имеет неверный формат, отозван или истёк; см. Истечение срока действия ключа). На Claude Platform на AWS это также может указывать на проблему с вашими учётными данными AWS или подписью SigV4.

• 402 - billing_error: Возникла проблема с вашей платёжной информацией. Проверьте свои платёжные данные в Claude Console или в AWS Marketplace, если вы используете Claude Platform на AWS.

• 403 - permission_error: Ваш ключ API не имеет разрешения на использование указанного ресурса. Проверьте настройки доступа и рабочего пространства вашей организации в Claude Console.

• 404 - not_found_error: Запрошенный ресурс не найден. Проверьте путь конечной точки и любые идентификаторы ресурсов в URL запроса.

• 409 - conflict_error: Запрос конфликтует с текущим состоянием ресурса. Например, ресурс был изменён одновременно, или значение, которое должно быть уникальным, уже используется. Разрешите конфликт, затем повторите запрос.

• 413 - request_too_large: Запрос превышает максимально допустимое количество байтов. См. Ограничения размера запроса для максимумов по каждой конечной точке.

• 429 - rate_limit_error: Ваша учётная запись достигла ограничения скорости (rate limit).

• 500 - api_error: Произошла непредвиденная ошибка внутри систем Anthropic. Повторите запрос с экспоненциальной задержкой; если ошибка сохраняется, обратитесь в поддержку, указав идентификатор запроса.

• 504 - timeout_error: Время ожидания запроса истекло во время обработки. Рассмотрите возможность использования потоковой передачи Messages API для длительных запросов. См. Длительные запросы для дополнительных вариантов.

• 529 - overloaded_error: API временно перегружен.

Официальные SDK автоматически повторяют запросы при временных сбоях (таких как ошибки соединения, ограничения скорости и серверные ошибки 5xx) с экспоненциальной задержкой, по умолчанию дважды, учитывая заголовок retry-after, если он присутствует. Каждый клиент SDK принимает параметр максимального количества повторов для настройки или отключения этого поведения.

При получении ответа с потоковой передачей через события, отправляемые сервером (server-sent events, SSE), ошибка может возникнуть после того, как API вернул ответ 200. В этом случае обработка ошибок не следует этим стандартным механизмам. См. События ошибок для формата ошибок в середине потока.



Ограничения размера запроса

API применяет ограничения на размер запроса:

Если вы превысите эти ограничения, вы получите ошибку 413 request_too_large. В прямом Claude API Cloudflare возвращает эту ошибку до того, как запрос достигнет серверов API.



Форматы ошибок

API всегда возвращает ошибки в формате JSON с объектом верхнего уровня error, который всегда включает значения type и message. Ответ также включает поле request_id для более удобного отслеживания и отладки. Например:

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "The requested resource could not be found."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

В соответствии с политикой версионирования, значения внутри этих объектов могут расширяться, и возможно, что значения type со временем будут увеличиваться.



Типы ошибок SDK

Официальные SDK вызывают типизированные исключения для этих ошибок вместо возврата необработанного JSON, и имена классов и пространства имён различаются в зависимости от языка. Например, ошибка 404 проявляется как anthropic.NotFoundError в Python, Anthropic::Errors::NotFoundError в Ruby, com.anthropic.errors.NotFoundException в Java и как единое значение *anthropic.Error (с ветвлением по StatusCode) в Go. Перехватывайте типизированные классы SDK, а не сопоставляйте строки сообщений об ошибках, обрабатывая сначала наиболее специфичные классы. На странице каждого SDK задокументирована его полная иерархия исключений:

• Python · TypeScript · C# · Go · Java · PHP · Ruby



Идентификатор запроса

Каждый ответ API включает уникальный заголовок request-id. Этот заголовок содержит значение, такое как req_018EeWyXxfu5pfWkrYcMdjWG. Тот же идентификатор появляется как поле request_id в телах ответов с ошибками. При обращении в поддержку по поводу конкретного запроса укажите этот идентификатор, чтобы помочь быстро решить вашу проблему.

На Claude Platform на AWS ответы включают два идентификатора запроса: идентификатор запроса AWS (x-amzn-requestid, основной, индексируется в CloudTrail) и идентификатор запроса Anthropic (request-id, вторичный). Используйте идентификатор запроса AWS для поиска в CloudTrail и идентификатор запроса Anthropic для обращений в поддержку Anthropic.

SDK для Python и TypeScript предоставляют идентификатор запроса как свойство _request_id в объектах ответа верхнего уровня. SDK для C#, Go, Java и PHP предоставляют его через свои методы доступа к необработанному ответу, которые также позволяют читать любой другой заголовок ответа. На Claude Platform на AWS используйте метод доступа к необработанному ответу, чтобы также прочитать идентификатор запроса AWS (x-amzn-requestid):

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(f"Request ID: {message._request_id}")

Примеры работы с идентификаторами запросов для Claude Platform на AWS на других языках см. в разделе Идентификаторы запросов.



Длительные запросы

Избегайте установки большого значения max_tokens без использования потоковой передачи Messages API или Message Batches API:

• Некоторые сети могут разрывать неактивные соединения через переменный период времени, что может привести к сбою запроса или истечению времени ожидания без получения ответа от Anthropic.
• Сети различаются по надёжности. Message Batches API может помочь вам управлять риском сетевых проблем, позволяя опрашивать результаты вместо того, чтобы требовать непрерывного сетевого соединения.

Если вы создаёте прямую интеграцию с API, установка TCP socket keep-alive может снизить влияние тайм-аутов неактивных соединений в некоторых сетях.

SDK проверяют, что ваши непотоковые запросы к Messages API не должны превышать 10-минутный тайм-аут. Они также устанавливают параметр сокета для TCP keep-alive.

Если вам не нужно обрабатывать события инкрементально, SDK могут обработать поток за вас и вернуть полный объект Message, идентичный тому, что возвращает непотоковый вызов:

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=128000,
    messages=[{"role": "user", "content": "Write a detailed analysis..."}],
    model="claude-sonnet-5",
) as stream:
    message = stream.get_final_message()

print(next(block.text for block in message.content if block.type == "text"))

Подробнее см. в разделе Потоковая передача сообщений.



Распространённые ошибки валидации



Предзаполнение не поддерживается

Модели Claude 4.6 и более поздние, а также Claude Mythos Preview не поддерживают предзаполнение сообщений ассистента. Отправка запроса с предзаполненным последним сообщением ассистента любой из этих моделей возвращает ошибку 400 invalid_request_error:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "This model does not support assistant message prefill. The conversation must end with a user message."
  }
}

Вместо этого используйте структурированные выводы на моделях, которые их поддерживают, инструкции в системной подсказке или output_config.format.



Блоки мышления нельзя изменять

Если самое последнее сообщение ассистента содержит блоки thinking или redacted_thinking, которые были отредактированы, переупорядочены, отфильтрованы или реконструированы перед отправкой обратно в API, запрос возвращает ошибку 400 invalid_request_error. Сообщение об ошибке начинается с позиции проблемного блока (например, messages.1.content.0) и содержит:

`thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified. These blocks must remain as they were in the original response.

При использовании инструментов каждый блок thinking и redacted_thinking из хода ассистента должен быть передан обратно точно в том виде, в каком он был получен, включая блоки, у которых поле thinking пустое. Передавайте блоки мышления обратно без изменений, и если ваше приложение фильтрует блоки содержимого по типу перед повторной отправкой, включайте как thinking, так и redacted_thinking. См. Устранение неполадок мышления, Сохранение блоков мышления и Вывод мышления на Claude Fable 5 и Claude Mythos 5.



Расширенное мышление не поддерживается

В моделях Claude 4.7 и более поздних расширенное мышление удалено. Отправка thinking: {"type": "enabled"} любой из этих моделей возвращает ошибку 400 invalid_request_error:

"thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

Вместо этого используйте адаптивное мышление. Раздел Миграция на адаптивное мышление показывает соответствие параметров, а Устранение неполадок мышления описывает исправление, исходя из симптомов.



Адаптивное мышление не поддерживается

Модели, которые поддерживают только расширенное мышление (Claude 4.5 и более ранние модели), отклоняют thinking: {"type": "adaptive"} с ошибкой 400 invalid_request_error:

adaptive thinking is not supported on this model

Используйте thinking: {"type": "enabled", "budget_tokens": N} на этих моделях; см. Расширенное мышление для конфигурации и Устранение неполадок мышления для исправления, исходя из симптомов.



Мышление нельзя отключить

На Claude Fable 5, Claude Mythos 5 и Claude Mythos Preview мышление всегда включено. Отправка thinking: {"type": "disabled"} любой из этих моделей возвращает ошибку 400 invalid_request_error:

"thinking.type.disabled" is not supported for this model. Thinking defaults to adaptive mode when not specified; use "thinking.type.enabled" with "budget_tokens" for extended thinking.

На Claude Fable 5 и Claude Mythos 5 предложение "thinking.type.enabled" из самого сообщения об ошибке также отклоняется. Опустите параметр thinking, и запрос будет выполнен с адаптивным мышлением. Чтобы исключить содержимое мышления из ответов, не отключая мышление, установите display: "omitted" в конфигурации мышления. См. Устранение неполадок мышления.



Исходящая федерация веб-идентификации отключена (Claude Platform на AWS)

Если каждый запрос к Claude Platform на AWS возвращает "Outbound web identity federation is disabled for your account", выполните aws iam enable-outbound-web-identity-federation один раз для каждой учётной записи AWS. Подробности см. в разделе Включение исходящей федерации веб-идентификации.



Следующие шаги