오류



HTTP 오류

API는 예측 가능한 HTTP 오류 코드 형식을 따릅니다:

• 400 - invalid_request_error: 요청의 형식 또는 내용에 문제가 있습니다. 이 오류 유형은 이 섹션에 나열되지 않은 다른 4XX 상태 코드에도 사용될 수 있습니다.

• 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 키에 지정된 리소스를 사용할 권한이 없습니다.

• 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 트래픽이 높을 때 발생할 수 있습니다.

  드물게 조직의 사용량이 급격히 증가하는 경우, API의 가속 제한으로 인해 429 오류가 표시될 수 있습니다. 가속 제한에 도달하지 않으려면 트래픽을 점진적으로 늘리고 일관된 사용 패턴을 유지하세요.

SSE를 통해 스트리밍 응답을 받을 때는 200 응답을 반환한 후에 오류가 발생할 수 있으며, 이 경우 오류 처리는 이러한 표준 메커니즘을 따르지 않습니다.



요청 크기 제한

API는 최적의 성능을 보장하기 위해 요청 크기 제한을 적용합니다:

이러한 제한을 초과하면 413 request_too_large 오류가 반환됩니다. 직접 Claude API에서는 요청이 API 서버에 도달하기 전에 Cloudflare에서 이 오류가 반환됩니다.



오류 형태

오류는 항상 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는 Python에서는 anthropic.NotFoundError로, Ruby에서는 Anthropic::Errors::NotFoundError로, Java에서는 com.anthropic.errors.NotFoundException으로, Go에서는 단일 *anthropic.Error 값(StatusCode로 분기)으로 나타납니다. 오류 메시지를 문자열 매칭하는 대신 SDK의 타입이 지정된 클래스를 catch하고, 가장 구체적인 클래스를 먼저 처리하세요. 각 SDK 페이지에서 전체 예외 계층 구조를 문서화하고 있습니다:

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



요청 ID

모든 API 응답에는 고유한 request-id 헤더가 포함됩니다. 이 헤더에는 req_018EeWyXxfu5pfWkrYcMdjWG와 같은 값이 포함됩니다. 특정 요청에 대해 지원팀에 문의할 때 이 ID를 포함하면 문제를 신속하게 해결하는 데 도움이 됩니다.

Claude Platform on AWS에서는 응답에 두 개의 요청 ID가 포함됩니다: AWS 요청 ID(x-amzn-requestid, 기본, CloudTrail에서 인덱싱됨)와 Anthropic 요청 ID(request-id, 보조). CloudTrail 조회에는 AWS 요청 ID를 사용하고, Anthropic 지원 티켓에는 Anthropic 요청 ID를 사용하세요.

공식 SDK는 최상위 응답 객체의 속성으로 Anthropic 요청 ID를 제공하며, 이는 request-id 헤더의 값을 포함합니다. Claude Platform on AWS에서는 원시 응답 접근자를 사용하여 HTTP 헤더에서 AWS 요청 ID도 읽을 수 있습니다:

다른 언어의 Claude Platform on AWS 요청 ID 예제는 요청 ID를 참조하세요.



장시간 요청

스트리밍 Messages API 또는 Message Batches API를 사용하지 않고 큰 max_tokens 값을 설정하는 것은 피하세요:

• 일부 네트워크는 가변적인 시간이 지난 후 유휴 연결을 끊을 수 있으며, 이로 인해 Anthropic으로부터 응답을 받지 못한 채 요청이 실패하거나 시간 초과될 수 있습니다.
• 네트워크는 안정성이 각기 다릅니다. Message Batches API는 중단 없는 네트워크 연결을 요구하는 대신 결과를 폴링할 수 있게 하여 네트워크 문제의 위험을 관리하는 데 도움이 됩니다.

직접 API 통합을 구축하는 경우, TCP 소켓 keep-alive를 설정하면 일부 네트워크에서 유휴 연결 시간 초과의 영향을 줄일 수 있다는 점을 알아두어야 합니다.

SDK는 비스트리밍 Messages API 요청이 10분 시간 초과를 넘지 않을 것으로 예상되는지 검증하며, TCP keep-alive를 위한 소켓 옵션도 설정합니다.

이벤트를 점진적으로 처리할 필요가 없는 경우, 이벤트 처리 코드를 작성하지 않고도 완전한 Message 객체를 얻으려면 .stream()과 함께 .get_final_message()(Python) 또는 .finalMessage()(TypeScript)를 사용하세요:

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)

자세한 내용은 스트리밍 메시지를 참조하세요.



일반적인 유효성 검사 오류



Prefill 미지원

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은 어시스턴트 메시지 "prefill"(사전 채우기)을 지원하지 않습니다. 이러한 모델 중 하나에 마지막 어시스턴트 메시지가 사전 채워진 요청을 보내면 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 블록은 수정할 수 없음

가장 최근의 어시스턴트 메시지에 API로 다시 전송되기 전에 편집, 재정렬, 필터링 또는 재구성된 thinking 또는 redacted_thinking 블록이 포함된 경우, 요청은 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 블록을 변경하지 않고 다시 전달하고, 애플리케이션이 재전송 전에 콘텐츠 블록을 유형별로 필터링하는 경우 thinking과 redacted_thinking을 모두 포함하세요. Thinking 블록 보존 및 Claude Fable 5 및 Claude Mythos 5의 Thinking 출력을 참조하세요.



아웃바운드 웹 ID 페더레이션 비활성화됨 (Claude Platform on AWS)

Claude Platform on AWS에 대한 모든 요청이 "Outbound web identity federation is disabled for your account"를 반환하는 경우, AWS 계정당 한 번 aws iam enable-outbound-web-identity-federation을 실행하세요. 자세한 내용은 아웃바운드 웹 ID 페더레이션 활성화를 참조하세요.