Ошибки Claude API

Ошибки HTTP

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

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

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

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

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

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

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

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

• 429 - rate_limit_error: ваша организация достигла одного из лимитов. Это может быть rate limit (ограничение скорости), месячный лимит расходов её уровня использования или лимит расходов для рабочего пространства Claude Code. Ошибка 429 из-за лимита расходов уровня не содержит заголовка retry-after и продолжает возникать до возобновления доступа. Как её распознать, см. в разделе Достижение лимита расходов.

• 500 - api_error: внутри систем Anthropic произошла непредвиденная ошибка. Повторите запрос с «exponential backoff» (экспоненциальной задержкой). Если ошибка сохраняется, обратитесь в службу поддержки и укажите «request ID» (идентификатор запроса).

• 504 - timeout_error: время ожидания запроса истекло во время обработки. Для длительных запросов рассмотрите возможность использования Messages API со «streaming» (потоковой передачей). Другие варианты см. в разделе Длительные запросы.

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

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

Ответ с потоковой передачей приходит через «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. В Go SDK для всех статусов используется один тип ошибки, *anthropic.Error, поэтому выполняйте ветвление по StatusCode. Перехватывайте типизированные классы SDK, а не сопоставляйте строки сообщений об ошибках. Сначала обрабатывайте наиболее специфичные классы. Полная иерархия исключений описана на странице каждого SDK:

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

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

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

В Claude Platform on AWS ответы включают два идентификатора запроса:

• идентификатор запроса AWS (x-amzn-requestid) — основной, индексируется в CloudTrail;
• идентификатор запроса Anthropic (request-id) — дополнительный.

Используйте идентификатор запроса AWS для поиска в CloudTrail, а идентификатор запроса Anthropic — для обращений в службу поддержки Anthropic.

SDK для Python и TypeScript предоставляют идентификатор запроса в виде свойства _request_id у объектов ответа верхнего уровня. SDK для C#, Go, Java и PHP предоставляют его через свои методы доступа к необработанному ответу, а SDK для Ruby — через middleware. Во всех SDK, кроме Ruby, используйте with_raw_response, чтобы прочитать любой другой заголовок ответа. Например, так можно прочитать anthropic-organization-id и anthropic-workspace-id. В Ruby используйте то же middleware. В Claude Platform on 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 on 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 не поддерживают «prefill» (предварительное заполнение) сообщений ассистента. Если отправить любой из этих моделей запрос с предварительно заполненным последним сообщением ассистента, API вернёт ошибку 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."
  }
}

Вместо этого используйте один из вариантов:

• «structured outputs» (структурированные выходные данные) на моделях, которые их поддерживают;
• инструкции в «system prompt» (системной подсказке);
• 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.

При «tool use» (использовании инструментов) каждый блок thinking и redacted_thinking из хода ассистента нужно передать обратно точно в том виде, в котором он был получен. Это относится и к блокам с пустым полем thinking. Передавайте блоки размышлений («thinking») обратно без изменений. Если ваше приложение перед повторной отправкой фильтрует блоки содержимого по типу, включайте как thinking, так и redacted_thinking. См. Устранение неполадок с размышлениями, Сохранение блоков размышлений и Сохранённые размышления.

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

В моделях Claude 4.7 и более поздних «extended thinking» (расширенные размышления) удалены. Отправка 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.

Вместо этого используйте «adaptive thinking» (адаптивные размышления). Соответствие параметров показано в разделе Переход на адаптивные размышления. Исправление, начиная с симптома, описано в разделе Устранение неполадок с размышлениями.

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

Модели, поддерживающие только расширенные размышления (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.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5 и Claude Mythos Preview. Отправка thinking: {"type": "disabled"} любой из этих моделей возвращает ошибку 400 invalid_request_error. Во всех этих моделях, кроме Claude Mythos Preview, сообщение выглядит так:

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

Claude Mythos Preview — единственная из этих моделей, которая принимает расширенные размышления. В ней сообщение выглядит так:

"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 Sonnet 5.5 для размышлений нельзя установить значение disabled. Минимальный уровень размышлений задаётся через thinking: {"type": "between_tools"}: этот режим отключает предварительные размышления. Отправка thinking: {"type": "disabled"} возвращает ошибку 400 invalid_request_error со следующим сообщением:

"thinking.type.disabled" is not supported for this model. Use "thinking.type.between_tools" for the lowest thinking setting, or "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

При уровне effort (усилие) xhigh или max запрос с between_tools также возвращает ошибку 400 invalid_request_error. В сообщении говорится, что размышления отключены, поскольку в режиме between_tools нет предварительных размышлений:

output_config.effort 'xhigh' is not supported when thinking is disabled on this model. Use effort 'high' or below, or enable thinking.

В режиме between_tools уровень усилия нельзя изменить посреди разговора. Если output_config.effort для отдельного сообщения отличается от действующего уровня, API возвращает ошибку 400. В ошибке указывается позиция сообщения, которое установило новый уровень:

messages.N: output_config.effort 'low' differs from the 'high' in effect before it; effort cannot change when thinking is disabled on this model. Use effort 'high', or enable thinking.

В обоих сообщениях «enable thinking» означает адаптивные размышления: опустите поле thinking или отправьте thinking: {"type": "adaptive"}. Claude Sonnet 5.5 отклоняет "enabled" с ошибкой 400. Чтобы менять уровень усилия от хода к ходу, используйте адаптивные размышления.

Отправка thinking: {"type": "between_tools"} любой модели, кроме Claude Sonnet 5.5, возвращает ошибку 400 invalid_request_error:

"thinking.type.between_tools" is not supported for this model.

Исправления ошибок between_tools и ошибок уровня усилия см. в разделе Устранение неполадок с размышлениями.

Если опустить параметр thinking, запрос будет выполнен с адаптивными размышлениями. Чтобы исключить содержимое размышлений из ответов, не отключая сами размышления, установите display: "omitted" в конфигурации размышлений. См. Устранение неполадок с размышлениями.

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

Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 и Claude Mythos 5.1 не поддерживают принудительное использование инструментов. Отправка tool_choice: {"type": "any"} или tool_choice: {"type": "tool", "name": "..."} любой из этих моделей возвращает ошибку 400 invalid_request_error. Это относится и к эндпоинту подсчёта токенов:

tool_choice: type "tool" and "any" are not supported for this model.

Значения tool_choice: {"type": "auto"} (по умолчанию) и {"type": "none"} принимаются. Чтобы входные данные инструментов соответствовали схеме, используйте auto со строгим использованием инструментов. Если сам ответ должен иметь фиксированную структуру JSON, используйте структурированные выходные данные. См. Принудительное использование инструментов.

Версия инструмента computer use не поддерживается

В Claude API и Google Cloud модели Claude Opus 5.5 и Claude Sonnet 5.5 поддерживают computer use (использование компьютера) только в виде набора инструментов computer_toolset_20260801. На этих платформах запись tools более раннего типа computer_20251124 (с бета-заголовком этого инструмента) приводит к ошибке 400 invalid_request_error для любой из этих моделей. В сообщении указывается отклонённый тип, а после Did you mean one of перечисляются типы инструментов, которые модель принимает. Для Claude Opus 5.5 сообщение начинается так:

'claude-opus-5-5' does not support tool types: computer_20251124.

API возвращает то же сообщение для любого определённого Anthropic типа инструмента, который запрошенная модель не поддерживает. Объявите {"type": "computer_toolset_20260801"} без бета-заголовка и обновите цикл агента, как описано в разделе Переход с computer_20251124. Более ранние модели, поддерживающие этот набор инструментов, по-прежнему принимают computer_20251124, как и Claude Opus 5.5 и Claude Sonnet 5.5 на Amazon Bedrock.

Блок размышлений больше не соответствует разговору

Для Claude Fable 5.1, Claude Opus 5.5 и Claude Sonnet 5.5 API принимает повторно переданный блок размышлений, только если подсказка system, tools и предшествующие блоку сообщения не изменились. Если предшествующая история изменилась, такой блок отклоняется с ошибкой 400 invalid_request_error в двух случаях:

• для новых аккаунтов, созданных 31 августа 2026 года или позже;
• для любого запроса, в котором thinking.block_binding.prefix_mismatch_behavior установлен в "error".

При значении "drop_block" API отбрасывает блок, и запрос выполняется успешно. Сообщение об ошибке начинается с позиции первого блока, не прошедшего проверку:

messages.{i}.content.{j}: Invalid `signature` in `thinking` block. The block is bound to a different conversation. Remove the block, or set `thinking.block_binding.prefix_mismatch_behavior` to "drop_block".

Если бета-заголовок thinking-binding-controls-2026-08-01 не передан, сообщение также называет этот заголовок. Чтобы избежать ошибки, только добавляйте сообщения в историю разговора, не изменяя её. Другой вариант — отправить бета-заголовок с prefix_mismatch_behavior: "drop_block", чтобы отбросить блок и продолжить. В Claude Sonnet 5.5 block_binding работает только с thinking: {"type": "adaptive"}. В режиме between_tools только добавляйте сообщения в историю или удаляйте блоки размышлений, начиная с отредактированного хода. Блок от модели, которую целевая модель не может прочитать, отбрасывается, а не отклоняется. См. Сохранение префикса без изменений и Устранение неполадок с размышлениями.

Если отправить thinking.block_binding без бета-заголовка thinking-binding-controls-2026-08-01, API вернёт ошибку 400 invalid_request_error. Её сообщение заканчивается так:

block_binding: Extra inputs are not permitted

Добавьте заголовок или удалите поле.

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

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

Дальнейшие шаги