--- title: Claude API 오류 url: https://platform.claude.com/docs/ko/api/errors description: Claude API가 반환하는 HTTP 상태 코드, 오류 응답 형식, 요청 ID를 이해하고 SDK의 타입이 지정된 예외로 오류를 처리하는 방법을 알아봅니다. --- ## HTTP 오류 API는 예측 가능한 HTTP 오류 코드 형식을 따릅니다: * 400 - `invalid_request_error`: 요청의 형식이나 내용에 문제가 있습니다. 이 오류 유형은 이 섹션에 나열되지 않은 다른 4XX 상태 코드에도 사용될 수 있습니다. 사용량이 조직 또는 워크스페이스에 [직접 설정한 지출 한도](https://platform.claude.com/docs/ko/api/rate-limits#setting-your-own-spend-limit)에 도달한 경우에도 API는 400을 반환합니다. 단, [Claude Code 워크스페이스](https://platform.claude.com/docs/ko/manage-claude/workspaces#claude-code-workspace)의 한도는 예외이며, 이 경우 대신 429가 반환될 수 있습니다. * 401 - `authentication_error`: [API 키](https://platform.claude.com/docs/ko/get-api-key)에 문제가 있습니다(예: 형식이 잘못되었거나, 취소되었거나, 만료된 경우. [키 만료](https://platform.claude.com/docs/ko/manage-claude/authentication#key-expiration)를 참조하세요). Claude Platform on AWS에서는 AWS 자격 증명 또는 SigV4 서명에 문제가 있음을 나타낼 수도 있습니다. * 402 - `billing_error`: 청구 또는 결제 정보에 문제가 있습니다. [Claude Console](https://platform.claude.com)에서, 또는 Claude Platform on AWS를 사용하는 경우 AWS Marketplace에서 결제 세부 정보를 확인하세요. * 403 - `permission_error`: API 키에 지정된 리소스를 사용할 권한이 없습니다. [Claude Console](https://platform.claude.com)에서 조직의 액세스 및 워크스페이스 설정을 확인하세요. * 404 - `not_found_error`: 요청한 리소스를 찾을 수 없습니다. 요청 URL의 엔드포인트 경로와 리소스 ID를 확인하세요. * 409 - `conflict_error`: 요청이 리소스의 현재 상태와 충돌합니다. 예를 들어 리소스가 동시에 수정되었거나, 고유해야 하는 값이 이미 사용 중인 경우입니다. 충돌을 해결한 후 요청을 다시 시도하세요. * 413 - `request_too_large`: 요청이 허용된 최대 바이트 수를 초과합니다. 엔드포인트별 최대값은 [요청 크기 제한](https://platform.claude.com/docs/ko/api/errors#request-size-limits)을 참조하세요. * 429 - `rate_limit_error`: 조직이 [속도 제한](https://platform.claude.com/docs/ko/api/rate-limits)에 도달했거나, 사용량 티어의 월간 지출 상한에 도달했거나, Claude Code 워크스페이스의 지출 한도에 도달했습니다. 티어 지출 상한으로 인한 429에는 `retry-after` 헤더가 없으며 액세스가 재개될 때까지 계속 실패합니다. 이를 식별하는 방법은 [지출 상한 도달](https://platform.claude.com/docs/ko/api/rate-limits#reaching-your-spend-cap)을 참조하세요. * 500 - `api_error`: Anthropic 시스템 내부에서 예기치 않은 오류가 발생했습니다. "exponential backoff"(지수 백오프)를 사용하여 요청을 다시 시도하세요. 오류가 지속되면 [요청 ID](https://platform.claude.com/docs/ko/api/errors#request-id)와 함께 지원팀에 문의하세요. * 504 - `timeout_error`: 처리 중 요청 시간이 초과되었습니다. 장시간 실행되는 요청에는 [스트리밍 Messages API](https://platform.claude.com/docs/ko/build-with-claude/streaming) 사용을 고려하세요. 추가 옵션은 [긴 요청](https://platform.claude.com/docs/ko/api/errors#long-requests)을 참조하세요. * 529 - `overloaded_error`: API가 일시적으로 과부하 상태입니다. 529 오류는 API가 모든 사용자에 걸쳐 높은 트래픽을 겪을 때 발생할 수 있습니다. 드물게 조직의 사용량이 급격히 증가하면 API의 가속 제한으로 인해 429 오류가 표시될 수 있습니다. 가속 제한에 도달하지 않으려면 트래픽을 점진적으로 늘리고 일관된 사용 패턴을 유지하세요. 공식 SDK는 일시적인 실패(연결 오류, 속도 제한, 5xx 서버 오류 등)를 지수 백오프로 자동 재시도하며, 기본적으로 두 번 재시도하고 `retry-after` 헤더가 있으면 이를 따릅니다. SDK 클라이언트는 이 동작을 구성하거나 비활성화하기 위해 `max_retries` (typescript, java, php: `maxRetries`; csharp: `MaxRetries`; go: `option.WithMaxRetries`)를 받습니다. "server-sent events"(서버 전송 이벤트), 즉 SSE를 통해 [스트리밍](https://platform.claude.com/docs/ko/build-with-claude/streaming) 응답을 받는 경우, API가 200 응답을 반환한 후에 오류가 발생할 수 있습니다. 이 경우 오류 처리는 이러한 표준 메커니즘을 따르지 않습니다. 스트림 도중 발생하는 오류의 형식은 [오류 이벤트](https://platform.claude.com/docs/ko/build-with-claude/streaming#error-events)를 참조하세요. ## 요청 크기 제한 API는 요청 크기 제한을 적용합니다: | 엔드포인트 유형 | 최대 요청 크기 | | ----------------------------------------------------------------------------------- | -------- | | Messages API | 32 MB | | Token Counting API | 32 MB | | [Batch API](https://platform.claude.com/docs/ko/build-with-claude/batch-processing) | 256 MB | | [Files API](https://platform.claude.com/docs/ko/build-with-claude/files) | 500 MB | 이 제한을 초과하면 413 `request_too_large` 오류를 받게 됩니다. 직접 Claude API에서는 요청이 API 서버에 도달하기 전에 Cloudflare가 이 오류를 반환합니다. ## 오류 형태 API는 항상 오류를 JSON으로 반환하며, 최상위 `error` 객체에는 항상 `type`과 `message` 값이 포함됩니다. 응답에는 추적과 디버깅을 쉽게 하기 위한 `request_id` 필드도 포함됩니다. 예를 들어: ```json JSON { "type": "error", "error": { "type": "not_found_error", "message": "The requested resource could not be found." }, "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy" } ``` [버전 관리](https://platform.claude.com/docs/ko/api/versioning) 정책에 따라 이러한 객체 내의 값은 확장될 수 있으며, `type` 값이 시간이 지남에 따라 늘어날 수 있습니다. ## SDK 오류 유형 공식 SDK는 원시 JSON을 반환하는 대신 이러한 오류에 대해 타입이 지정된 예외를 발생시킵니다. 예를 들어 404는 `anthropic.NotFoundError` (typescript: `Anthropic.NotFoundError`; ruby: `Anthropic::Errors::NotFoundError`; java: `com.anthropic.errors.NotFoundException`; csharp: `AnthropicNotFoundException`; php: `Anthropic\Core\Exceptions\NotFoundException`; go: `*anthropic.Error`)로 나타납니다. Go SDK는 모든 상태에 대해 하나의 오류 유형 `*anthropic.Error`를 사용하므로 `StatusCode`로 분기하세요. 오류 메시지를 문자열로 매칭하는 대신 SDK의 타입이 지정된 클래스를 포착하고, 가장 구체적인 클래스부터 처리하세요. 전체 예외 계층 구조는 각 SDK 페이지에 문서화되어 있습니다: * [Python](https://platform.claude.com/docs/ko/cli-sdks-libraries/sdks/python#handling-errors) · [TypeScript](https://platform.claude.com/docs/ko/cli-sdks-libraries/sdks/typescript#handling-errors) · [C#](https://platform.claude.com/docs/ko/cli-sdks-libraries/sdks/csharp#error-handling) · [Go](https://platform.claude.com/docs/ko/cli-sdks-libraries/sdks/go#error-handling) · [Java](https://platform.claude.com/docs/ko/cli-sdks-libraries/sdks/java#error-handling) · [PHP](https://platform.claude.com/docs/ko/cli-sdks-libraries/sdks/php#error-handling) · [Ruby](https://platform.claude.com/docs/ko/cli-sdks-libraries/sdks/ruby#handling-errors) ## 요청 ID 모든 API 응답에는 고유한 `request-id` 헤더가 포함됩니다. 이 헤더에는 `req_018EeWyXxfu5pfWkrYcMdjWG`와 같은 값이 들어 있습니다. 동일한 식별자가 [오류 응답 본문](https://platform.claude.com/docs/ko/api/errors#error-shapes)의 `request_id` 필드로도 나타납니다. 특정 요청에 대해 지원팀에 문의할 때 이 ID를 포함하면 문제를 빠르게 해결하는 데 도움이 됩니다. [Claude Platform on AWS](https://platform.claude.com/docs/ko/build-with-claude/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는 [미들웨어](https://platform.claude.com/docs/ko/cli-sdks-libraries/middleware)를 통해 이를 노출합니다. Ruby를 제외한 모든 SDK에서는 `with_raw_response` (typescript: `.withResponse()`; java: `.withRawResponse()`; csharp: `WithRawResponse`; go: `option.WithResponseInto`; php: `->raw`)를 사용하여 `anthropic-organization-id` 및 [`anthropic-workspace-id`](https://platform.claude.com/docs/ko/manage-claude/workspaces#identify-the-workspace-behind-an-api-response)와 같은 다른 [응답 헤더](https://platform.claude.com/docs/ko/api/overview#response-headers)를 읽을 수 있습니다. Ruby에서는 동일한 미들웨어를 사용하세요. Claude Platform on AWS에서는 원시 응답 접근자를 사용하여 AWS 요청 ID(`x-amzn-requestid`)도 읽을 수 있습니다: ```bash cURL # 응답 헤더(request-id 포함)를 출력하고 본문은 버립니다 curl -sS -D - -o /dev/null https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-sonnet-5", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello, Claude"}] }' ``` ```bash CLI # request-id 헤더는 --debug 사용 시 stderr에 출력됩니다: ant --debug messages create \ --model claude-sonnet-5 \ --max-tokens 1024 \ --message '{role: user, content: "Hello, Claude"}' ``` ```python Python 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}") ``` ```typescript TypeScript const client = new Anthropic(); const message = await client.messages.create({ model: "claude-sonnet-5", max_tokens: 1024, messages: [{ role: "user", content: "Hello, Claude" }] }); console.log("Request ID:", message._request_id); ``` ```csharp C# AnthropicClient client = new(); using var response = await client.WithRawResponse.Messages.Create(new MessageCreateParams { Model = Model.ClaudeSonnet5, MaxTokens = 1024, Messages = [new() { Role = Role.User, Content = "Hello, Claude" }] }); Console.WriteLine($"Request ID: {response.RequestID}"); ``` ```go Go client := anthropic.NewClient() var response *http.Response _, err := client.Messages.New( context.Background(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeSonnet5, MaxTokens: 1024, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, Claude")), }, }, option.WithResponseInto(&response), ) if err != nil { panic(err) } fmt.Println("Request ID:", response.Header.Get("request-id")) ``` ```java Java import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.core.http.HttpResponseFor; import com.anthropic.models.messages.Message; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Model; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); HttpResponseFor response = client.messages().withRawResponse().create( MessageCreateParams.builder() .model(Model.CLAUDE_SONNET_5) .maxTokens(1024) .addUserMessage("Hello, Claude") .build() ); IO.println("Request ID: " + response.requestId().orElse(null)); } ``` ```php PHP $client = new Client(); $response = $client->messages->raw->create([ 'model' => 'claude-sonnet-5', 'maxTokens' => 1024, 'messages' => [['role' => 'user', 'content' => 'Hello, Claude']], ]); echo 'Request ID: ' . $response->getHeaderLine('request-id') . "\n"; ``` ```ruby Ruby client = Anthropic::Client.new # 요청별 미들웨어에서 응답 헤더를 읽습니다. 이 미들웨어는 # SDK가 파싱하기 전의 원시 HTTP 응답을 받습니다 request_id = nil read_request_id = lambda do |request, call_next| response = call_next.call(request) # response.headers의 키는 소문자입니다 request_id = response.headers["request-id"] response end client.messages.create( model: Anthropic::Model::CLAUDE_SONNET_5, max_tokens: 1024, messages: [{ role: "user", content: "Hello, Claude" }], request_options: { middleware: [read_request_id] } ) puts "Request ID: #{request_id}" ``` ```python Python (Claude Platform on AWS) from anthropic import AnthropicAWS client = AnthropicAWS(aws_region="us-west-2") response = client.messages.with_raw_response.create( model="claude-opus-5-5", max_tokens=1024, messages=[{"role": "user", "content": "Hello, Claude"}], ) print(f"AWS request ID: {response.headers.get('x-amzn-requestid')}") message = response.parse() print(f"Anthropic request ID: {message._request_id}") ``` ```typescript TypeScript (Claude Platform on AWS) import AnthropicAws from "@anthropic-ai/aws-sdk"; const client = new AnthropicAws({ awsRegion: "us-west-2" }); const { response: raw, request_id } = await client.messages .create({ model: "claude-opus-5-5", max_tokens: 1024, messages: [{ role: "user", content: "Hello, Claude" }] }) .withResponse(); console.log("AWS request ID:", raw.headers.get("x-amzn-requestid")); console.log("Anthropic request ID:", request_id); ``` 다른 언어의 Claude Platform on AWS 요청 ID 예제는 [요청 ID](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#request-ids)를 참조하세요. ## 긴 요청 장시간 실행되는 요청, 특히 10분을 초과하는 요청에는 [스트리밍 Messages API](https://platform.claude.com/docs/ko/build-with-claude/streaming) 또는 [Message Batches API](https://platform.claude.com/docs/ko/api/messages/batches/create) 사용을 고려하세요. [스트리밍 Messages API](https://platform.claude.com/docs/ko/build-with-claude/streaming) 또는 [Message Batches API](https://platform.claude.com/docs/ko/api/messages/batches/create)를 사용하지 않고 큰 `max_tokens` 값을 설정하지 마세요: * 일부 네트워크는 일정하지 않은 시간이 지나면 유휴 연결을 끊을 수 있으며, 이로 인해 Anthropic으로부터 응답을 받지 못한 채 요청이 실패하거나 시간 초과될 수 있습니다. * 네트워크마다 안정성이 다릅니다. [Message Batches API](https://platform.claude.com/docs/ko/api/messages/batches/create)는 중단 없는 네트워크 연결을 요구하는 대신 결과를 폴링할 수 있게 하여 네트워크 문제의 위험을 관리하는 데 도움이 됩니다. API를 직접 통합하는 경우, [TCP 소켓 keep-alive](https://tldp.org/HOWTO/TCP-Keepalive-HOWTO/programming.html)를 설정하면 일부 네트워크에서 유휴 연결 시간 초과의 영향을 줄일 수 있습니다. [SDK](https://platform.claude.com/docs/ko/cli-sdks-libraries/overview)는 비스트리밍 Messages API 요청이 10분 시간 제한을 초과하지 않을 것으로 예상되는지 검증합니다. 또한 TCP keep-alive를 위한 소켓 옵션을 설정합니다. 이벤트를 점진적으로 처리할 필요가 없다면, SDK가 스트림을 대신 소비하여 비스트리밍 호출이 반환하는 것과 동일한 완전한 `Message` 객체를 반환할 수 있습니다: curl 요청은 원시 스트림 이벤트를 출력하며 이를 최종 메시지로 결합할 수 없습니다. 스트림에서 완전한 `Message` 객체를 얻으려면 [Claude SDK](https://platform.claude.com/docs/ko/cli-sdks-libraries/overview)를 사용하세요. ```bash CLI # CLI는 이벤트를 스트리밍합니다. --format jsonl은 한 줄에 이벤트 하나씩 출력합니다 ant messages create --stream --format jsonl <<'YAML' model: claude-sonnet-5 max_tokens: 128000 messages: - role: user content: Write a detailed analysis... YAML ``` ```python Python 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")) ``` ```typescript TypeScript const client = new Anthropic(); const stream = client.messages.stream({ max_tokens: 128000, messages: [{ role: "user", content: "Write a detailed analysis..." }], model: "claude-sonnet-5" }); const message = await stream.finalMessage(); const textBlock = message.content.find((block) => block.type === "text"); if (textBlock && textBlock.type === "text") { console.log(textBlock.text); } ``` ```csharp C# AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeSonnet5, MaxTokens = 128000, Messages = [new() { Role = Role.User, Content = "Write a detailed analysis..." }] }; var message = await client.Messages.CreateStreaming(parameters).Aggregate(); Console.WriteLine(message); ``` ```go Go client := anthropic.NewClient() stream := client.Messages.NewStreaming(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeSonnet5, MaxTokens: 128000, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Write a detailed analysis...")), }, }) message := anthropic.Message{} for stream.Next() { event := stream.Current() if err := message.Accumulate(event); err != nil { log.Fatal(err) } } if err := stream.Err(); err != nil { log.Fatal(err) } for _, block := range message.Content { if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok { fmt.Println(textBlock.Text) break } } ``` ```java Java import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.helpers.MessageAccumulator; import com.anthropic.models.messages.ContentBlock; import com.anthropic.models.messages.Message; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Model; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_SONNET_5) .maxTokens(128000L) .addUserMessage("Write a detailed analysis...") .build(); MessageAccumulator accumulator = MessageAccumulator.create(); try (var streamResponse = client.messages().createStreaming(params)) { streamResponse.stream().forEach(accumulator::accumulate); } Message message = accumulator.message(); message.content().stream() .filter(ContentBlock::isText) .findFirst() .flatMap(ContentBlock::text) .ifPresent(textBlock -> IO.println(textBlock.text())); } ``` ```php PHP use Anthropic\Lib\Streaming\MessageAccumulator; $client = new Client(); $stream = $client->messages->createStream( model: 'claude-sonnet-5', maxTokens: 128000, messages: [['role' => 'user', 'content' => 'Write a detailed analysis...']], ); $accumulator = MessageAccumulator::forMessages(); foreach ($stream as $event) { $accumulator->accumulate($event); } echo array_find($accumulator->message()->content, static fn ($block): bool => $block->type === 'text')->text; ``` ```ruby Ruby client = Anthropic::Client.new message = client.messages.stream( model: "claude-sonnet-5", max_tokens: 128000, messages: [{ role: "user", content: "Write a detailed analysis..." }] ).accumulated_message puts message.content.find { it.type == :text }.text ``` 자세한 내용은 [메시지 스트리밍](https://platform.claude.com/docs/ko/build-with-claude/streaming#get-the-final-message-without-handling-events)을 참조하세요. ## 일반적인 검증 오류 ### 프리필 미지원 Claude 4.6 이상 모델과 [Claude Mythos Preview](https://anthropic.com/glasswing)는 어시스턴트 메시지 "prefill"(프리필)을 지원하지 않습니다. 이러한 모델에 마지막 어시스턴트 메시지가 프리필된 요청을 보내면 400 `invalid_request_error`가 반환됩니다: ```json { "type": "error", "error": { "type": "invalid_request_error", "message": "This model does not support assistant message prefill. The conversation must end with a user message." } } ``` 대신 이를 지원하는 모델에서 [구조화된 출력](https://platform.claude.com/docs/ko/build-with-claude/structured-outputs), 시스템 프롬프트 지침 또는 [`output_config.format`](https://platform.claude.com/docs/ko/build-with-claude/structured-outputs#usage)을 사용하세요. ### thinking 블록은 수정할 수 없음 가장 최근의 어시스턴트 메시지에 API로 다시 전송되기 전에 편집, 재정렬, 필터링 또는 재구성된 `thinking` 또는 `redacted_thinking` 블록이 포함되어 있으면 요청은 400 `invalid_request_error`를 반환합니다. 오류 메시지는 문제가 되는 블록의 위치(예: `messages.1.content.0`)로 시작하며 다음을 포함합니다: ```text wrap `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`을 모두 포함하세요. [사고 문제 해결](https://platform.claude.com/docs/ko/build-with-claude/thinking-troubleshooting#error-thinking-blocks-modified), [thinking 블록 보존](https://platform.claude.com/docs/ko/build-with-claude/thinking#preserving-thinking-blocks), [보존된 사고](https://platform.claude.com/docs/ko/build-with-claude/thinking#preserved-thinking)를 참조하세요. ### 확장 사고 미지원 Claude 4.7 이상 모델에서는 extended thinking(확장 사고)이 제거되었습니다. 이러한 모델에 `thinking: {"type": "enabled"}`를 보내면 400 `invalid_request_error`가 반환됩니다: ```text wrap "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior. ``` 대신 [적응형 사고](https://platform.claude.com/docs/ko/build-with-claude/thinking)를 사용하세요. [적응형 사고로 마이그레이션](https://platform.claude.com/docs/ko/build-with-claude/extended-thinking#migrating-to-adaptive-thinking)에서 매개변수 매핑을 보여주며, [사고 문제 해결](https://platform.claude.com/docs/ko/build-with-claude/thinking-troubleshooting#error-thinking-type-enabled)에서 증상 우선 해결 방법을 다룹니다. ### 적응형 사고 미지원 확장 사고만 지원하는 모델(Claude 4.5 이하 모델)은 `thinking: {"type": "adaptive"}`를 400 `invalid_request_error`로 거부합니다: ```text wrap adaptive thinking is not supported on this model ``` 이러한 모델에서는 `thinking: {"type": "enabled", "budget_tokens": N}`을 사용하세요. 구성은 [확장 사고](https://platform.claude.com/docs/ko/build-with-claude/extended-thinking)를, 증상 우선 해결 방법은 [사고 문제 해결](https://platform.claude.com/docs/ko/build-with-claude/thinking-troubleshooting#error-thinking-type-adaptive)을 참조하세요. ### 사고를 비활성화할 수 없음 Claude Fable 5.1, [Claude Mythos 5.1](https://platform.claude.com/docs/ko/models/mythos-5-1/overview), Claude Fable 5, [Claude Mythos 5](https://platform.claude.com/docs/ko/models/mythos-5/overview), Claude Opus 5.5, [Claude Mythos Preview](https://anthropic.com/glasswing)에서는 사고가 항상 켜져 있습니다. 이러한 모델에 `thinking: {"type": "disabled"}`를 보내면 400 `invalid_request_error`가 반환됩니다. Claude Mythos Preview를 제외한 이 모든 모델에서 메시지는 다음과 같습니다: ```text wrap "thinking.type.disabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior. ``` 이 모델 중 유일하게 확장 사고를 허용하는 Claude Mythos Preview에서는 메시지가 다음과 같습니다: ```text wrap "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`가 반환됩니다: ```text wrap 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](https://platform.claude.com/docs/ko/build-with-claude/effort)에서는 `between_tools`를 사용한 요청도 400 `invalid_request_error`를 반환합니다. `between_tools`에는 사전 사고가 없으므로 메시지는 사고가 비활성화되어 있다고 표시합니다: ```text wrap 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 오류를 반환합니다. 오류에는 새 수준을 설정한 메시지의 위치가 표시됩니다: ```text wrap 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 오류로 거부합니다. 턴마다 effort를 다르게 하려면 적응형 사고를 사용하세요. Claude Sonnet 5.5 이외의 모델에 `thinking: {"type": "between_tools"}`를 보내면 400 `invalid_request_error`가 반환됩니다: ```text wrap "thinking.type.between_tools" is not supported for this model. ``` 해결 방법은 `between_tools` 및 effort 오류를 다루는 [사고 문제 해결](https://platform.claude.com/docs/ko/build-with-claude/thinking-troubleshooting#error-thinking-type-between-tools)을 참조하세요. `thinking` 매개변수를 생략하면 요청은 적응형 사고로 실행됩니다. 사고를 끄지 않고 응답에서 사고 내용을 제외하려면 사고 구성에 `display: "omitted"`를 설정하세요. [사고 문제 해결](https://platform.claude.com/docs/ko/build-with-claude/thinking-troubleshooting#error-thinking-type-disabled)을 참조하세요. ### 강제 도구 사용 미지원 Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1, [Claude Mythos 5.1](https://platform.claude.com/docs/ko/models/mythos-5-1/overview)은 "forced tool use"(강제 도구 사용)를 지원하지 않습니다. [토큰 카운팅 엔드포인트](https://platform.claude.com/docs/ko/build-with-claude/token-counting)를 포함하여 이러한 모델에 `tool_choice: {"type": "any"}` 또는 `tool_choice: {"type": "tool", "name": "..."}`를 보내면 400 `invalid_request_error`가 반환됩니다: ```text wrap tool_choice: type "tool" and "any" are not supported for this model. ``` `tool_choice: {"type": "auto"}`(기본값)와 `{"type": "none"}`은 허용됩니다. 도구 입력이 스키마에 맞도록 유지하려면 `auto`를 [엄격한 도구 사용](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/strict-tool-use)과 함께 사용하고, 응답 자체가 고정된 JSON 형식이어야 하는 경우 [구조화된 출력](https://platform.claude.com/docs/ko/build-with-claude/structured-outputs)을 사용하세요. [도구 사용 강제](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/define-tools#forcing-tool-use)를 참조하세요. ### 컴퓨터 사용 도구 버전 미지원 Claude API와 Google Cloud에서 Claude Opus 5.5, Claude Sonnet 5.5, Claude Haiku 5.5는 [컴퓨터 사용](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool)을 `computer_toolset_20260801` 도구 세트로만 지원합니다. 해당 플랫폼에서 이러한 모델에 이전 `computer_20251124` 또는 `computer_20250124` 유형의 `tools` 항목을 해당 도구의 베타 헤더와 함께 보내면 400 `invalid_request_error`가 반환됩니다. 메시지는 거부된 유형을 명시한 다음, `Did you mean one of` 뒤에 모델이 허용하는 도구 유형을 나열합니다. Claude Opus 5.5의 경우 다음과 같이 시작합니다: ```text wrap 'claude-opus-5-5' does not support tool types: computer_20251124. ``` API는 요청한 모델이 지원하지 않는 모든 Anthropic 정의 도구 유형에 대해 동일한 메시지를 반환합니다. 베타 헤더 없이 `{"type": "computer_toolset_20260801"}`을 선언하고 [`computer_20251124`에서 마이그레이션](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124)에 설명된 대로 에이전트 루프를 업데이트하세요. `computer_20250124`에서 이전하려면 Claude Haiku 5.5 마이그레이션 가이드의 [컴퓨터 사용을 도구 세트로 이동하기](https://platform.claude.com/docs/ko/models/haiku-5-5/migration-guide#computer-use-toolset)를 참조하세요. 도구 세트를 지원하는 이전 모델은 계속 `computer_20251124`를 허용하며, Amazon Bedrock의 Claude Opus 5.5, Claude Sonnet 5.5, Claude Haiku 5.5도 마찬가지입니다. ### 사고 블록이 더 이상 대화와 일치하지 않음 Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5, Claude Haiku 5.5에서는 재전송된 사고 블록 앞에 있던 `system` 프롬프트, `tools`, 메시지가 변경되지 않은 경우에만 API가 해당 블록을 허용합니다. 2026년 8월 31일 이후에 생성된 신규 계정과 `thinking.block_binding.prefix_mismatch_behavior`를 `"error"`로 설정한 모든 요청의 경우, 이전 기록이 변경된 재전송 블록은 400 `invalid_request_error`로 거부됩니다(`"drop_block"`을 사용하면 API가 블록을 삭제하고 요청이 성공합니다). 메시지는 처음 실패한 블록의 위치로 시작합니다: ```text wrap 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"`과 함께 베타 헤더를 보내 블록을 삭제하고 계속 진행하세요. Claude Sonnet 5.5와 Claude Haiku 5.5에서 `block_binding`은 `thinking: {"type": "adaptive"}`에서만 작동합니다. Claude Sonnet 5.5에서 `between_tools`를 사용하거나 Claude Haiku 5.5에서 `thinking: {"type": "disabled"}`를 사용하는 경우, 기록을 추가 전용으로 유지하거나 편집된 턴부터 사고 블록을 제거하세요. 대상 모델이 읽을 수 없는 모델의 블록은 거부되지 않고 삭제됩니다. [접두사를 변경하지 않고 유지하기](https://platform.claude.com/docs/ko/build-with-claude/preserved-thinking#prefix-check) 및 [사고 문제 해결](https://platform.claude.com/docs/ko/build-with-claude/thinking-troubleshooting#error-thinking-block-signature)을 참조하세요. `thinking-binding-controls-2026-08-01` [베타 헤더](https://platform.claude.com/docs/ko/api/beta-headers) 없이 `thinking.block_binding`을 보내면 메시지가 다음으로 끝나는 400 `invalid_request_error`가 반환됩니다: ```text wrap block_binding: Extra inputs are not permitted ``` 헤더를 추가하거나 필드를 제거하세요. ### 아웃바운드 웹 ID 페더레이션 비활성화됨 (Claude Platform on AWS) [Claude Platform on AWS](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws)에 대한 모든 요청이 `"Outbound web identity federation is disabled for your account"`를 반환하면, AWS 계정당 한 번 `aws iam enable-outbound-web-identity-federation`을 실행하세요. 자세한 내용은 [아웃바운드 웹 ID 페더레이션 활성화](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#enable-outbound-web-identity-federation)를 참조하세요. ## 다음 단계 thinking 구성 400 오류, 빈 thinking 블록, `max_tokens` 중단에 대한 증상 우선 해결 방법. API의 오용을 완화하고 용량을 관리하기 위해 조직이 Claude API를 사용할 수 있는 양에 제한이 있습니다. 텍스트, 도구 사용, 확장 사고 델타를 포함하여 server-sent events로 Messages API 응답을 점진적으로 스트리밍하세요.