Claude API 오류

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에서, 또는 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: 조직이 rate limit(속도 제한)에 도달했거나, 사용 등급의 월간 지출 상한에 도달했거나, Claude Code 워크스페이스의 지출 한도에 도달했습니다. 등급 지출 상한으로 인한 429에는 retry-after 헤더가 없으며 액세스가 재개될 때까지 계속 실패합니다. 이를 식별하는 방법은 지출 상한 도달을 참조하세요.

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

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

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

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

server-sent events(SSE)를 통해 streaming(스트리밍) 응답을 수신할 때, 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의 타입 지정 클래스를 포착하고, 가장 구체적인 클래스를 먼저 처리하세요. 각 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는 원시 응답 접근자를 통해, Ruby SDK는 미들웨어를 통해 이를 노출합니다. 동일한 메커니즘과 Python의 with_raw_response, TypeScript의 .withResponse()를 사용하면 anthropic-organization-id 및 anthropic-workspace-id와 같은 다른 응답 헤더도 읽을 수 있습니다. 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"))

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

일반적인 검증 오류

프리필 미지원

Claude 4.6 이상 모델과 Claude Mythos Preview는 어시스턴트 메시지 프리필을 지원하지 않습니다. 이러한 모델에 마지막 어시스턴트 메시지가 프리필된 요청을 보내면 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.

tool use(도구 사용) 시, 어시스턴트 턴의 모든 thinking 및 redacted_thinking 블록은 thinking 필드가 비어 있는 블록을 포함하여 받은 그대로 정확히 다시 전달해야 합니다. thinking 블록을 변경 없이 다시 전달하고, 애플리케이션이 재전송 전에 콘텐츠 블록을 유형별로 필터링한다면 thinking과 redacted_thinking을 모두 포함하세요. 사고 문제 해결, thinking 블록 보존, 보존된 사고를 참조하세요.

확장 사고 미지원

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

대신 적응형 사고를 사용하세요. 적응형 사고로 마이그레이션에서 매개변수 매핑을 보여주며, 사고 문제 해결에서 증상 우선 해결 방법을 다룹니다.

적응형 사고 미지원

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

adaptive thinking is not supported on this model

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

사고를 비활성화할 수 없음

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

"thinking.type.disabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

이 모델들 중 유일하게 확장 사고를 허용하는 Claude Mythos Preview에서는 메시지가 다음과 같습니다:

"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.

thinking 매개변수를 생략하면 요청이 적응형 사고로 실행됩니다. Thinking을 끄지 않고 응답에서 thinking 콘텐츠를 제외하려면 thinking 구성에서 display: "omitted"를 설정하세요. Thinking 문제 해결을 참조하세요.

강제 도구 사용 미지원

Claude Fable 5.1과 Claude Mythos 5.1은 강제 도구 사용을 지원하지 않습니다. 토큰 카운팅 엔드포인트를 포함하여 두 모델 중 하나에 tool_choice: {"type": "any"} 또는 tool_choice: {"type": "tool", "name": "..."}를 보내면 400 invalid_request_error가 반환됩니다:

tool_choice: type "tool" and "any" are not supported for this model.

tool_choice: {"type": "auto"}(기본값)와 {"type": "none"}은 허용됩니다. 도구 입력을 스키마에 맞게 유지하려면 auto를 엄격한 도구 사용과 함께 사용하고, 응답 자체가 고정된 JSON 형태여야 할 때는 구조화된 출력을 사용하세요. 도구 사용 강제를 참조하세요.

thinking 블록이 더 이상 대화와 일치하지 않음

Claude Fable 5.1에서 API는 재전송된 thinking 블록을 그 앞에 있던 system 프롬프트, tools, 메시지가 변경되지 않은 경우에만 허용합니다. 2026년 8월 31일 이후에 생성된 신규 계정과 thinking.block_binding.prefix_mismatch_behavior를 "error"로 설정한 모든 요청의 경우, 이전 기록이 변경된 재전송 블록은 400 invalid_request_error로 거부됩니다("drop_block"을 사용하면 API가 블록을 삭제하고 요청은 성공합니다). 메시지는 첫 번째 실패 블록의 위치로 시작합니다:

messages.{i}.content.{j}: Invalid `signature` in `thinking` block. The block is bound to a different conversation. Remove the block, or set `thinking.block_binding.prefix_mismatch_behavior` to "drop_block".

thinking-binding-controls-2026-08-01 베타 헤더가 없으면 메시지에 해당 헤더 이름도 표시됩니다. 대화 기록을 추가 전용으로 유지하거나, prefix_mismatch_behavior: "drop_block"과 함께 베타 헤더를 보내 블록을 삭제하고 계속 진행하세요. 대상 모델이 읽을 수 없는 모델의 블록은 거부되지 않고 삭제됩니다. 접두사를 변경하지 않고 유지하기 및 Thinking 문제 해결을 참조하세요.

thinking-binding-controls-2026-08-01 베타 헤더 없이 thinking.block_binding을 보내면 메시지가 다음으로 끝나는 400 invalid_request_error가 반환됩니다:

block_binding: Extra inputs are not permitted

헤더를 추가하거나 필드를 제거하세요.

아웃바운드 웹 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 페더레이션 활성화를 참조하세요.

다음 단계