Ошибки Claude API
Узнайте о кодах состояния HTTP, структуре ответа об ошибке и идентификаторах запросов, которые возвращает Claude API, и обрабатывайте ошибки с помощью типизированных исключений SDK.
Ошибки HTTP
API использует предсказуемый формат кодов ошибок HTTP:
-
400 -
invalid_request_error: возникла проблема с форматом или содержимым вашего запроса. API также может использовать этот тип ошибки для других кодов состояния 4XX, не перечисленных в этом разделе. API также возвращает 400, когда использование достигает установленного вами лимита расходов для организации или рабочего пространства. Исключение составляют лимиты для рабочего пространства Claude Code: вместо этого они могут возвращать 429. Если в сообщении указана проблема с вашим запросом, найдите её в разделе Распространённые ошибки валидации. -
401 -
authentication_error: возникла проблема с вашим ключом API (например, он имеет неверный формат, отозван или истёк; см. Истечение срока действия ключа). В Claude Platform on AWS это также может указывать на проблему с вашими учётными данными AWS или подписью SigV4.Ошибка 401, сообщение которой начинается с
CORS requests are not allowed for this Organization, не связана с вашим ключом API. Запрос содержал заголовокOrigin, который добавляют браузеры, а ваша организация не может обращаться к Claude API напрямую из браузера. Далее сообщение продолжается словамиbecause of custom retention settingsилиbecause of its settings. Первый вариант появляется только при особых условиях хранения данных, таких как “zero data retention” (нулевое хранение данных), или ZDR; второй — общий случай, который включает Compliance API. Никакие изменения запроса из браузера этого не исправят, поэтому отправляйте запрос из своего собственного “back end” (серверная часть); см. Браузерные приложения. -
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и продолжает возникать до восстановления доступа; как её распознать, см. в разделе Достижение предела расходов. Резкий рост использования также может вызвать ошибку 429, даже если вы не превышаете ограничения скорости; см. «Ramp limits» (ограничения наращивания). -
500 -
api_error: во внутренних системах Anthropic произошла непредвиденная ошибка. Повторите запрос с экспоненциальной задержкой; если ошибка сохраняется, обратитесь в службу поддержки, указав идентификатор запроса. Если же тип ошибки —timeout_error, см. пункт о коде 504. -
504 -
timeout_error: время ожидания запроса истекло во время обработки. API также возвращаетtimeout_errorс другими кодами состояния, например 500, когда запрос достигает ограничения времени сервера до начала ответа. Для длительных запросов к Messages API используйте Messages API с потоковой передачей. Дополнительные варианты см. в разделе Длительные запросы. -
529 -
overloaded_error: API временно перегружен.
Официальный SDK автоматически повторяет запросы при временных сбоях (таких как ошибки соединения, ограничения скорости и серверные ошибки 5xx) с экспоненциальной задержкой — по умолчанию дважды, учитывая заголовок retry-after, если он присутствует. Клиент SDK принимает max_retries для настройки или отключения этого поведения.
При получении ответа с потоковой передачей через «server-sent events» (события, отправляемые сервером), или SSE, ошибка может возникнуть после того, как API вернул ответ 200. В этом случае обработка ошибок не следует этим стандартным механизмам. Структуру ошибок, возникающих в середине потока, см. в разделе События ошибок.
Ограничения размера запроса
Собственный Claude API применяет следующие ограничения размера запроса. Для других платформ см. обзор API.
| Тип эндпоинта | Максимальный размер запроса |
|---|---|
| Messages API | 128 MB |
| Token Counting API | 128 MB |
| Batch API | 256 MB |
| Files API | 500 MB |
При превышении этих ограничений вы получите ошибку 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"
}В соответствии с политикой версионирования API набор значений внутри этих объектов может расширяться, и могут появиться новые значения type.
Типы ошибок SDK
Официальный SDK выбрасывает типизированные исключения для этих ошибок вместо возврата необработанного JSON. Например, ошибка 404 проявляется как anthropic.NotFoundError. В Go SDK есть один тип ошибки для всех статусов — *anthropic.Error: выполняйте ветвление по StatusCode. Перехватывайте типизированные классы SDK, а не сопоставляйте строки сообщений об ошибках, обрабатывая сначала наиболее специфичные классы. Полная иерархия исключений описана на странице вашего SDK:
Идентификатор запроса
Каждый ответ 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 — через промежуточное ПО. Во всех 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Доступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape.:
- Некоторые сети могут разрывать неактивные соединения через произвольный промежуток времени, что может привести к сбою запроса или истечению времени ожидания без получения ответа от Anthropic.
- Сети различаются по надёжности. Message Batches APIДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape. может помочь вам управлять риском сетевых проблем, позволяя опрашивать результаты вместо того, чтобы требовать непрерывного сетевого соединения.
Если вы создаёте прямую интеграцию с API, установка keep-alive для TCP-сокета может снизить влияние тайм-аутов неактивных соединений в некоторых сетях.
Anthropic 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.
Блоки размышлений нельзя изменять
Если блоки размышлений в запросе не совпадают с тем, что вернул 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. Это сбой, отличный от проверки префикса, ошибка которой сообщает, что блок привязан к другому разговору. Задание prefix_mismatch_behavior может не устранить её. См. исправление для изменённых блоков размышлений в разделе «Устранение неполадок с размышлениями».
Расширенные размышления не поддерживаются
Модели 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.Вместо этого используйте адаптивные размышления. Соответствие параметров см. в разделе Переход на адаптивные размышления. Чтобы исправить ошибку, исходя из её симптома, см. Ошибка 400 сообщает, что "thinking.type.enabled" не поддерживается.
Адаптивные размышления не поддерживаются
Модели, поддерживающие только расширенные размышления (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.2, Claude Mythos 5.2, 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 и Claude Haiku 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 Fable 5.2, Claude Mythos 5.2, 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. См. Принудительное использование инструментов.
Версия инструмента использования компьютера не поддерживается
Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5 и Claude Haiku 5.5 возвращают ошибку 400 для любой версии инструмента использования компьютера, которую они не принимают. В Claude API это включает computer_20251124 с его бета-заголовком. Они не принимают computer_20250124 ни на одной платформе. Сообщение invalid_request_error в Claude API называет отклонённый тип и после Did you mean one of перечисляет типы инструментов, которые принимает модель. Для Claude Opus 5.5 сообщение начинается так:
'claude-opus-5-5' does not support tool types: computer_20251124.Claude API возвращает то же сообщение для любого определённого Anthropic типа инструмента, который запрошенная модель не поддерживает. Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5 и Claude Haiku 5.5 поддерживают использование компьютера через набор инструментов computer_toolset_20260801. Объявите {"type": "computer_toolset_20260801"} без бета-заголовка и обновите цикл агента, как описано в разделе Миграция с computer_20251124. О переходе с computer_20250124 см. Перевод использования компьютера на набор инструментов в руководстве по миграции на Claude Haiku 5.5.
На Amazon Bedrock Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5 и Claude Haiku 5.5 также принимают инструмент computer_20251124 с бета-заголовком computer-use-2025-11-24. При использовании InvokeModel API от Amazon Bedrock передавайте computer-use-2025-11-24 в массиве anthropic_beta тела запроса, а не в заголовке. Об этом API см. Claude в Amazon Bedrock (bedrock-runtime). Модели, которые следует использовать с каждой более ранней версией, см. в разделе Более ранние версии инструмента.
Блок размышлений, привязанный к другому разговору
Эта ошибка 400 invalid_request_error означает, что отправленный вами обратно блок размышлений не прошёл проверку префикса. Сравните system, tools и сообщения перед блоком с тем, что вы отправили, когда модель создала этот блок. Какие изменения имеют значение, см. в разделе Что считается изменением. Сообщение об ошибке начинается с позиции первого блока, не прошедшего проверку префикса:
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и задайте дляthinking.block_binding.prefix_mismatch_behaviorзначение"drop_block"при повторной попытке и в каждом последующем запросе в этом разговоре. В Claude Sonnet 5.5 и Claude Haiku 5.5block_bindingработает только сthinking: {"type": "adaptive"}. - Удалите блок, указанный в ошибке, и все блоки
thinkingиredacted_thinkingпосле него — в этом сообщении и во всех последующих сообщениях. Повторите попытку и не включайте удалённые блоки в последующие запросы.
Чтобы новые разговоры не завершались ошибкой, сохраняйте историю в режиме «только добавление» (append-only). См. исправление для недействительной подписи блока размышлений в разделе «Устранение неполадок с размышлениями».
Отправка 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. Подробнее см. в разделе Включение исходящей федерации веб-удостоверений.
Дальнейшие шаги
Исправления, начиная с симптома: ошибки 400 в конфигурации размышлений, пустые блоки размышлений и остановки по max_tokens.
Чтобы предотвратить злоупотребления и управлять пропускной способностью API, объём использования Claude API организацией ограничен.
Получайте ответы Messages API постепенно через события, отправляемые сервером, включая дельты текста, использования инструментов и расширенных размышлений.
Эта страница была полезной?