오류



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: 요청한 리소스를 찾을 수 없습니다.

• 409 - conflict_error: 요청이 리소스의 현재 상태와 충돌합니다. 예를 들어, 리소스가 동시에 수정되었거나 고유해야 하는 값이 이미 사용 중입니다. 충돌을 해결한 후 요청을 다시 시도하세요.

• 413 - request_too_large: 요청이 허용되는 최대 바이트 수를 초과합니다. 엔드포인트별 최대값은 요청 크기 제한을 참조하세요.

• 429 - rate_limit_error: 계정이 속도 제한에 도달했습니다.

• 500 - api_error: Anthropic 시스템 내부에서 예기치 않은 오류가 발생했습니다.

• 504 - timeout_error: 처리 중 요청 시간이 초과되었습니다. 장시간 실행되는 요청에는 스트리밍 사용을 고려하세요. 더 많은 옵션은 긴 요청을 참조하세요.

• 529 - overloaded_error: API가 일시적으로 과부하 상태입니다.

  

  529 오류는 API가 모든 사용자에 걸쳐 높은 트래픽을 경험할 때 발생할 수 있습니다.

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

공식 SDK는 일시적인 실패(연결 오류, 속도 제한, 5xx 서버 오류 등)를 지수 백오프(exponential backoff)로 자동 재시도하며, 기본적으로 두 번 재시도하고 retry-after 헤더가 있는 경우 이를 준수합니다. 각 SDK 클라이언트는 이 동작을 구성하거나 비활성화할 수 있는 최대 재시도 옵션을 허용합니다.

서버 전송 이벤트(server-sent events, SSE)를 통해 스트리밍 응답을 받을 때, API가 200 응답을 반환한 후에 오류가 발생할 수 있습니다. 이 경우 오류 처리는 이러한 표준 메커니즘을 따르지 않습니다. 스트림 중간 오류의 형태는 오류 이벤트를 참조하세요.



요청 크기 제한

API는 요청 크기 제한을 적용합니다:

이러한 제한을 초과하면 413 request_too_large 오류가 발생합니다. 직접 Claude API에서는 요청이 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는 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와 같은 값이 포함됩니다. 동일한 식별자가 오류 응답 본문의 request_id 필드로 나타납니다. 특정 요청에 대해 지원팀에 문의할 때 이 ID를 포함하면 문제를 빠르게 해결하는 데 도움이 됩니다.

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

Python 및 TypeScript SDK는 최상위 응답 객체의 _request_id 속성으로 요청 ID를 노출합니다. C#, Go, Java, PHP SDK는 원시 응답 접근자(raw-response accessor)를 통해 이를 노출하며, 이를 통해 다른 응답 헤더도 읽을 수 있습니다. Claude Platform on AWS에서는 원시 응답 접근자를 사용하여 AWS 요청 ID(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 요청 ID 예제는 요청 ID를 참조하세요.



긴 요청

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

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

직접 API 통합을 구축하는 경우, TCP 소켓 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(message.content[0].text)

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



일반적인 검증 오류



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(사전 채우기)을 지원하지 않습니다. 이러한 모델에 마지막 어시스턴트 메시지가 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 페더레이션 활성화를 참조하세요.



다음 단계