Справочник APIИспользование API

Ошибки Claude API

Copy page



Узнайте о кодах состояния HTTP, структуре ответа об ошибке и идентификаторах запросов, которые возвращает Claude API, и обрабатывайте ошибки с помощью типизированных исключений SDK.

Ошибки 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 для упрощения отслеживания и отладки. Например: