Ошибки



Ошибки 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 не имеет разрешения на использование указанного ресурса.

• 404 - not_found_error: Запрошенный ресурс не найден.

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

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

• 500 - api_error: Произошла непредвиденная внутренняя ошибка в системах Anthropic.

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

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

  

  Ошибки 529 могут возникать, когда API испытывают высокий трафик от всех пользователей.

  В редких случаях, если в вашей организации наблюдается резкий рост использования, вы можете увидеть ошибки 429 из-за ограничений ускорения в API. Чтобы избежать достижения ограничений ускорения, наращивайте трафик постепенно и поддерживайте стабильные паттерны использования.

При получении ответа через потоковую передачу по SSE возможна ситуация, когда ошибка возникает после возврата ответа 200 — в этом случае обработка ошибок не будет следовать этим стандартным механизмам.



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

API применяет ограничения размера запроса для обеспечения оптимальной производительности:

Если вы превысите эти ограничения, вы получите ошибку 413 request_too_large. При прямом обращении к Claude API эта ошибка возвращается от Cloudflare до того, как запрос достигнет серверов 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. При обращении в службу поддержки по поводу конкретного запроса укажите этот идентификатор, чтобы помочь быстро решить вашу проблему.

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

Официальные SDK предоставляют идентификатор запроса Anthropic как свойство объектов ответа верхнего уровня, содержащее значение заголовка request-id. В Claude Platform на AWS используйте метод доступа к необработанному ответу, чтобы также прочитать идентификатор запроса AWS из HTTP-заголовков:

Примеры получения идентификатора запроса для 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.

Если вам не нужно обрабатывать события инкрементально, используйте .stream() с .get_final_message() (Python) или .finalMessage() (TypeScript), чтобы получить полный объект Message без написания кода обработки событий:

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

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



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



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

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

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Prefilling assistant messages is not supported for this model."
  }
}

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

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