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 서명에 문제가 있음을 나타낼 수도 있습니다.

  메시지가 CORS requests are not allowed for this Organization으로 시작하는 401 오류는 API 키의 문제가 아닙니다. 요청에 브라우저가 추가하는 Origin 헤더가 포함되어 있었으며, 귀하의 조직은 브라우저에서 Claude API를 직접 호출할 수 없습니다. 메시지는 because of custom retention settings 또는 because of its settings로 이어집니다. 전자는 “zero data retention”(데이터 무보존), 즉 ZDR과 같은 데이터 보존 약정에서만 나타나며, 후자는 Compliance API를 포함하는 일반적인 경우입니다. 브라우저 요청을 변경해도 이 문제는 해결되지 않으므로, 자체 백엔드에서 요청을 보내세요. 브라우저 기반 애플리케이션을 참조하세요.

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

• 500 - api_error: Anthropic 시스템 내부에서 예기치 않은 오류가 발생했습니다. “exponential backoff”(지수 백오프)를 사용하여 요청을 다시 시도하세요. 오류가 지속되면 요청 ID와 함께 지원팀에 문의하세요. 대신 오류 유형이 timeout_error인 경우 504 항목을 참조하세요.

• 504 - timeout_error: 처리 중 요청 시간이 초과되었습니다. API는 다른 상태 코드와 함께 timeout_error를 반환하기도 합니다. 예를 들어 응답이 시작되기 전에 요청이 서버의 시간 제한에 도달하면 500과 함께 반환합니다. 장시간 실행되는 Messages API 요청에는 스트리밍 Messages API를 사용하세요. 추가 옵션은 긴 요청을 참조하세요.

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

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

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

요청 크기 제한

퍼스트 파티 Claude API는 다음과 같은 요청 크기 제한을 적용합니다. 다른 플랫폼의 경우 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는 anthropic.NotFoundError로 나타납니다. Go SDK는 모든 상태에 대해 하나의 오류 유형 *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는 미들웨어를 통해 이를 노출합니다. Ruby를 제외한 모든 SDK에서는 with_raw_response를 사용하여 anthropic-organization-id 및 anthropic-workspace-id와 같은 다른 응답 헤더를 읽을 수 있습니다. Ruby에서는 동일한 미들웨어를 사용하세요. 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 APIAPI 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요.를 사용하지 않고 큰 max_tokens 값을 설정하지 마세요:

• 일부 네트워크는 가변적인 시간이 지나면 유휴 연결을 끊을 수 있으며, 이로 인해 Anthropic으로부터 응답을 받지 못한 채 요청이 실패하거나 시간 초과될 수 있습니다.
• 네트워크마다 안정성이 다릅니다. Message Batches APIAPI 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요.는 중단 없는 네트워크 연결을 요구하는 대신 결과를 폴링할 수 있게 하여 네트워크 문제의 위험을 관리하는 데 도움이 됩니다.

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

Claude 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는 어시스턴트 메시지 “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을 사용하세요.

사고 블록은 수정할 수 없음

가장 최근의 어시스턴트 메시지에 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과 redacted_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.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5, Claude Mythos Preview에서는 사고가 항상 켜져 있습니다. 이러한 모델에 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.

Claude Sonnet 5.5에서는 사고를 disabled로 설정할 수 없습니다. 가장 낮은 사고 설정으로는 사전 사고를 끄는 thinking: {"type": "between_tools"}를 사용하세요. thinking: {"type": "disabled"}를 보내면 다음 메시지와 함께 400 invalid_request_error가 반환됩니다:

To turn thinking off on this model, send "thinking": {"type": "between_tools"} instead of {"type": "disabled"}. The model does not think before responding. The short updates it writes between tool calls come back as thinking blocks.

xhigh 또는 max effort에서는 between_tools를 사용한 요청도 400 invalid_request_error를 반환합니다. between_tools에는 사전 사고가 없으므로 메시지는 사고가 비활성화되어 있다고 표시합니다:

output_config.effort 'xhigh' is not supported when thinking is disabled on this model. Use effort 'high' or below, or enable thinking.

between_tools를 사용하면 대화 도중 effort를 변경할 수 없습니다. 현재 적용 중인 수준과 다른 메시지별 output_config.effort는 400 오류를 반환합니다. 오류에는 새 수준을 설정한 메시지의 위치가 표시됩니다:

messages.N: output_config.effort 'low' differs from the 'high' in effect before it; effort cannot change when thinking is disabled on this model. Use effort 'high', or enable thinking.

Claude Haiku 5.5는 thinking: {"type": "disabled"}를 허용하며, between_tools에 적용되는 것과 동일한 두 가지 effort 제한을 적용합니다. xhigh 또는 max effort에서, 또는 적용 중인 수준과 다른 메시지별 output_config.effort를 사용하면 요청은 앞서 표시된 해당 메시지와 함께 400 invalid_request_error를 반환합니다.

두 메시지 모두에서 “enable thinking”은 적응형 사고를 의미합니다: thinking 필드를 생략하거나 thinking: {"type": "adaptive"}를 보내세요. Claude Sonnet 5.5와 Claude Haiku 5.5도 "enabled"를 400 오류로 거부합니다. 턴마다 노력 수준을 달리하려면 적응형 사고를 사용하세요.

Claude Sonnet 5.5 이외의 모델에 thinking: {"type": "between_tools"}를 보내면 400 invalid_request_error가 반환됩니다:

"thinking.type.between_tools" is not supported for this model.

해결 방법은 사고 문제 해결의 between_tools 및 effort 오류를 참조하세요.

thinking 매개변수를 생략하면 요청은 적응형 사고로 실행됩니다. 사고를 끄지 않고 응답에서 사고 내용을 제외하려면 사고 구성에 display: "omitted"를 설정하세요. 사고 문제 해결의 비활성화된 사고 오류에 대한 해결 방법을 참조하세요.

강제 도구 사용 미지원

Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1, Claude Mythos 5.1은 “forced tool use”(강제 도구 사용)를 지원하지 않습니다. 토큰 카운팅 엔드포인트를 포함하여 이러한 모델에 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 형식이어야 하는 경우 구조화된 출력을 사용하세요. 도구 사용 강제를 참조하세요.

컴퓨터 사용 도구 버전 미지원

Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5, Claude Haiku 5.5는 허용하지 않는 컴퓨터 사용 도구 버전에 대해 400 오류를 반환합니다. Claude API에서는 베타 헤더와 함께 사용하는 computer_20251124도 여기에 포함됩니다. 이 모델들은 어떤 플랫폼에서도 computer_20250124를 허용하지 않습니다. Claude API의 invalid_request_error 메시지는 거부된 유형을 명시하고, Did you mean one of 뒤에 모델이 허용하는 도구 유형을 나열합니다. Claude Opus 5.5의 경우 메시지는 다음과 같이 시작합니다:

'claude-opus-5-5' does not support tool types: computer_20251124.

Claude API는 요청한 모델이 지원하지 않는 모든 Anthropic 정의 도구 유형에 대해 동일한 메시지를 반환합니다. Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5, Claude Haiku 5.5는 computer_toolset_20260801 도구 세트를 통해 컴퓨터 사용을 지원합니다. 베타 헤더 없이 {"type": "computer_toolset_20260801"}을 선언하고, computer_20251124에서 마이그레이션에 설명된 대로 에이전트 루프를 업데이트하세요. computer_20250124에서 이전하려면 Claude Haiku 5.5 마이그레이션 가이드의 컴퓨터 사용을 도구 세트로 이전을 참조하세요.

Amazon Bedrock에서는 Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5, Claude Haiku 5.5가 computer-use-2025-11-24 베타 헤더와 함께 computer_20251124 도구도 허용합니다. 이전 도구 버전에는 각 이전 버전과 함께 사용할 모델이 나열되어 있습니다.

다른 대화에 바인딩된 사고 블록

이 400 invalid_request_error는 일반적으로 다시 보낸 사고 블록이 접두사 검사에 실패했음을 의미합니다. 즉, system 프롬프트, tools 또는 이전 메시지 등 블록 앞에 있는 무언가가 블록이 생성된 후에 변경된 것입니다. Claude 5.1 이상 모델이 이 검사를 수행합니다. prefix_mismatch_behavior를 설정하지 않은 요청의 경우, prefix_mismatch_behavior가 설정되지 않은 경우에서 어떤 요청이 이 오류를 받는지 확인할 수 있습니다. 메시지는 처음 실패한 블록의 위치로 시작합니다:

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 및 redacted_thinking 블록을 제거한 다음 한 번 재시도하세요. Claude Sonnet 5.5와 Claude Haiku 5.5에서 block_binding은 thinking: {"type": "adaptive"}에서만 작동하므로, 다른 사고 설정을 사용하는 경우에는 블록을 제거하세요. 새 대화가 실패하지 않도록 하려면 기록을 추가 전용(append-only)으로 유지하세요. 대상 모델이 읽을 수 없는 모델의 블록은 거부되지 않고 삭제됩니다. 접두사를 변경하지 않고 유지하기 및 사고 문제 해결의 유효하지 않은 사고 블록 서명에 대한 해결 방법을 참조하세요.

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 페더레이션 활성화를 참조하세요.

다음 단계