Claude API 오류



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 키에 지정된 리소스를 사용할 권한이 없습니다. Claude Console에서 조직의 액세스 및 워크스페이스 설정을 확인하세요.

• 404 - not_found_error: 요청한 리소스를 찾을 수 없습니다. 요청 URL의 엔드포인트 경로와 리소스 ID를 확인하세요.

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

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

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

• 500 - api_error: Anthropic 시스템 내부에서 예기치 않은 오류가 발생했습니다. 지수 백오프로 요청을 다시 시도하세요. 오류가 지속되면 요청 ID와 함께 지원팀에 문의하세요.

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

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

  

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

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

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

서버 전송 이벤트(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는 원시 응답 접근자를 통해 이를 노출하며, 이를 통해 다른 응답 헤더도 읽을 수 있습니다. 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(next(block.text for block in message.content if block.type == "text"))

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



일반적인 검증 오류



Prefill이 지원되지 않음

Claude 4.6 이상 모델과 Claude Mythos Preview는 어시스턴트 메시지 prefill(사전 채우기)을 지원하지 않습니다. 이러한 모델에 마지막 어시스턴트 메시지가 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."
  }
}

대신 이를 지원하는 모델에서 구조화된 출력, 시스템 프롬프트 지침, 또는 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 문제 해결, Thinking 블록 보존, Claude Fable 5 및 Claude Mythos 5의 thinking 출력을 참조하세요.



확장 사고가 지원되지 않음

Claude 4.7 이상 모델에서는 확장 사고가 제거되었습니다. 이러한 모델에 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.

대신 적응형 사고를 사용하세요. 적응형 사고로 마이그레이션에서 매개변수 매핑을 확인할 수 있으며, Thinking 문제 해결에서 증상 중심의 해결 방법을 다룹니다.



적응형 사고가 지원되지 않음

확장 사고만 지원하는 모델(Claude 4.5 이하 모델)은 thinking: {"type": "adaptive"}를 400 invalid_request_error로 거부합니다:

adaptive thinking is not supported on this model

이러한 모델에서는 thinking: {"type": "enabled", "budget_tokens": N}을 사용하세요. 구성은 확장 사고를, 증상 중심의 해결 방법은 Thinking 문제 해결을 참조하세요.



Thinking은 비활성화할 수 없음

Claude Fable 5, Claude Mythos 5, Claude Mythos Preview에서는 thinking이 항상 켜져 있습니다. 이러한 모델에 thinking: {"type": "disabled"}를 보내면 400 invalid_request_error가 반환됩니다:

"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 Fable 5 및 Claude Mythos 5에서는 오류 메시지 자체가 제안하는 "thinking.type.enabled"도 거부됩니다. thinking 매개변수를 생략하면 요청이 적응형 사고로 실행됩니다. Thinking을 끄지 않고 응답에서 thinking 콘텐츠를 제외하려면 thinking 구성에서 display: "omitted"를 설정하세요. 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 페더레이션 활성화를 참조하세요.



다음 단계