Ошибки 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 или в AWS Marketplace, если вы используете Claude Platform on 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» (ограничения скорости), месячного предела расходов своего уровня использования или лимита расходов для рабочего пространства Claude Code. Ошибка 429 из-за предела расходов уровня не содержит заголовка retry-after и продолжает возникать до восстановления доступа; как её распознать, см. в разделе Достижение предела расходов.

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

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

• 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» (предварительное заполнение) сообщений ассистента. Отправка запроса с предварительно заполненным последним сообщением ассистента любой из этих моделей возвращает ошибку 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."
  }
}

Вместо этого используйте структурированные выходные данные на моделях, которые их поддерживают, инструкции в «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 с таким сообщением:

To turn thinking off on this model, send "thinking": {"type": "between_tools"} instead of {"type": "disabled"}. The model does not think before responding. The short updates it writes between tool calls come back as thinking blocks.

При уровне усилий 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 для отдельного сообщения, отличающийся от действующего уровня, возвращает ошибку 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.

Claude Haiku 5.5 принимает thinking: {"type": "disabled"} и применяет к нему те же два ограничения на уровень усилий, что действуют для between_tools: при уровне усилий xhigh или max, либо при output_config.effort для отдельного сообщения, отличающемся от действующего уровня, запрос возвращает ошибку 400 invalid_request_error с соответствующим сообщением, приведённым выше.

В обоих сообщениях «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 и Claude Haiku 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 и Claude Haiku 5.5 API принимает повторно переданный блок размышлений только до тех пор, пока подсказка system, tools и предшествующие ему сообщения остаются неизменными. Для новых аккаунтов, созданных 31 августа 2026 года или позже, а также для любого запроса, в котором thinking.block_binding.prefix_mismatch_behavior установлен в "error", повторно переданный блок, предшествующая история которого изменилась, отклоняется с ошибкой 400 invalid_request_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 возвращает ошибку 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. Подробнее см. в разделе Включение исходящей федерации веб-удостоверений.

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