DEV Community: Sangmin Lee

Claude API vision_error (invalid_request_error): 원인과 해결법

Sangmin Lee — Sun, 05 Jul 2026 01:31:33 +0000

Originally published at claudeguide.io/claude-api-error-vision-error

Claude API vision_error (invalid_request_error): 원인과 해결법

Claude API vision_error invalid_request_error는 이미지 형식, 크기, 또는 인코딩이 모델 요구사항과 불일치에 발생합니다 (2026 기준). 이미지 입력 오류이며, 재시도하지 말고 요청 자체를 수정해야 합니다. 이 글은 5가지 흔한 원인과 Python/TypeScript 코드 예시를 다룹니다.

전반적인 Claude API 에러 처리 패턴은 Claude API Error Handling 가이드를 참고하세요.

무엇을 의미하는가?

vision_error 에러 서브타입는 이미지 형식, 크기, 또는 인코딩이 모델 요구사항과 불일치을 의미합니다. Anthropic API의 에러 응답 본문에는 error.type이 "invalid_request_error"로 명시되며, error.message에 구체적 사유가 옵니다.

응답 예시:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "..."
  }
}

흔한 원인 5가지

지원 안 되는 이미지 포맷 (예: WebP, BMP — JPEG/PNG/GIF/WebP만)
단일 이미지 5MB 초과 (base64 인코딩 후)
이미지 dimensions 8000×8000 초과
URL 이미지의 Content-Type이 image/* 아님

해결 코드 (Python)


python
# Validate image before sending
from PIL import Image
import io, base64

def safe_image_block(image_bytes: bytes):
    img = Image.open(io.BytesIO(image_bytes))
    if img.format not in ("JPEG", "PNG", "GIF", "WEBP"):
        raise ValueError(f"Unsupported format: {img.format}")
    if img.size[0]

Claude API tool_use_error (invalid_request_error): 원인과 해결법

Sangmin Lee — Sun, 05 Jul 2026 01:30:50 +0000

Originally published at claudeguide.io/claude-api-error-tool-use-error

Claude API tool_use_error (invalid_request_error): 원인과 해결법

Claude API tool_use_error invalid_request_error는 tool_choice / tool_result / tool_use 형식이 schema와 불일치에 발생합니다 (2026 기준). Tool use 형식 오류이며, 재시도하지 말고 요청 자체를 수정해야 합니다. 이 글은 5가지 흔한 원인과 Python/TypeScript 코드 예시를 다룹니다.

전반적인 Claude API 에러 처리 패턴은 Claude API Error Handling 가이드를 참고하세요.

무엇을 의미하는가?

tool_use_error 에러 서브타입는 tool_choice / tool_result / tool_use 형식이 schema와 불일치을 의미합니다. Anthropic API의 에러 응답 본문에는 error.type이 "invalid_request_error"로 명시되며, error.message에 구체적 사유가 옵니다.

응답 예시:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "..."
  }
}

흔한 원인 5가지

tool_use_id가 tool_result와 매칭 안 됨
tool_choice를 specific tool로 했지만 해당 tool 미정의
input_schema가 JSON Schema draft 2020-12 위반
messages에 tool_use는 있는데 다음 turn에 tool_result 없음

해결 코드 (Python)

# Validate tool_use → tool_result pairing before sending
def validate_tool_pairing(messages):
    pending_tool_uses = []
    for msg in messages:
        if msg["role"] == "assistant":
            for block in msg.get("content", []):
                if isinstance(block, dict) and block.get("type") == "tool_use":
                    pending_tool_uses.append(block["id"])
        elif msg["role"] == "user":
            for block in msg.get("content", []):
                if isinstance(block, dict) and block.get("type") == "tool_result":
                    if block["tool_use_id"] in pending_tool_uses:
                        pending_tool_uses.remove(block["tool_use_id"])
    if pending_tool_uses:
        raise ValueError(f"Unmatched tool_use IDs: {pending_tool_uses}")

해결 코드 (TypeScript)


typescript
function validateToolPairing(messages) {
  const pending: string[] = [];
  for (const msg of messages) {
    if (msg.role === "assistant") {
      for (const b of msg.content ?? []) {
        if (b.type === "tool_use") pending.push(b.id);
      }
    } else if (msg.role === "user") {
      for (const b of msg.content ?? []) {
        if (b.type === "tool_result") {
          const idx = pending.indexOf(b.tool_use_id);
          if (idx

Claude API streaming_error (api_error): 원인과 해결법

Sangmin Lee — Sun, 05 Jul 2026 01:30:47 +0000

Originally published at claudeguide.io/claude-api-error-streaming-error

Claude API streaming_error (api_error): 원인과 해결법

Claude API streaming_error api_error는 SSE 스트림이 중간에 끊기거나 malformed event 발생에 발생합니다 (2026 기준). 스트리밍 응답 중단이며, exponential backoff 재시도가 효과적해야 합니다. 이 글은 5가지 흔한 원인과 Python/TypeScript 코드 예시를 다룹니다.

전반적인 Claude API 에러 처리 패턴은 Claude API Error Handling 가이드를 참고하세요.

무엇을 의미하는가?

streaming_error 에러 서브타입는 SSE 스트림이 중간에 끊기거나 malformed event 발생을 의미합니다. Anthropic API의 에러 응답 본문에는 error.type이 "api_error"로 명시되며, error.message에 구체적 사유가 옵니다.

응답 예시:

{
  "type": "error",
  "error": {
    "type": "api_error",
    "message": "..."
  }
}

흔한 원인 5가지

긴 응답 중 connection timeout (

Claude API prompt_too_long (invalid_request_error): 원인과 해결법

Sangmin Lee — Sun, 05 Jul 2026 01:30:04 +0000

Originally published at claudeguide.io/claude-api-error-prompt-too-long

Claude API prompt_too_long (invalid_request_error): 원인과 해결법

Claude API prompt_too_long invalid_request_error는 단일 messages 또는 누적 conversation이 모델 context window 초과에 발생합니다 (2026 기준). 프롬프트가 너무 김이며, 재시도하지 말고 요청 자체를 수정해야 합니다. 이 글은 5가지 흔한 원인과 Python/TypeScript 코드 예시를 다룹니다.

전반적인 Claude API 에러 처리 패턴은 Claude API Error Handling 가이드를 참고하세요.

무엇을 의미하는가?

prompt_too_long 에러 서브타입는 단일 messages 또는 누적 conversation이 모델 context window 초과을 의미합니다. Anthropic API의 에러 응답 본문에는 error.type이 "invalid_request_error"로 명시되며, error.message에 구체적 사유가 옵니다.

응답 예시:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "..."
  }
}

흔한 원인 5가지

200K context 모델에 250K 토큰 입력
Long-running 챗봇의 누적 history 미관리
PDF/문서 첨부 토큰 미계산
RAG context를 무한정 추가

해결 코드 (Python)

# Trim conversation to fit budget before sending
def trim_to_budget(messages, system, model, output_budget=4096, ctx=200_000):
    client = anthropic.Anthropic()
    while True:
        count = client.messages.count_tokens(
            model=model, messages=messages, system=system
        ).input_tokens
        if count + output_budget <= ctx - 1000:
            return messages
        if len(messages) <= 2:
            # Fallback to summarize older content
            summary = summarize_old_msgs(messages[:-2])
            messages = [{"role": "user", "content": summary}] + messages[-2:]
        else:
            messages = messages[2:]  # drop oldest user+assistant pair

해결 코드 (TypeScript)

async function trimToBudget(messages, system, model, outputBudget = 4096, ctx = 200_000) {
  while (true) {
    const { input_tokens } = await client.messages.countTokens({ model, messages, system });
    if (input_tokens + outputBudget <= ctx - 1000) return messages;
    if (messages.length <= 2) {
      const summary = await summarizeOldMsgs(messages.slice(0, -2));
      messages = [{ role: "user", content: summary }, ...messages.slice(-2)];
    } else {
      messages = messages.slice(2);
    }
  }
}

재시도하지 마세요

이 에러는 클라이언트 측 문제라 재시도해도 같은 결과입니다. 위 원인을 확인하고 요청을 수정한 뒤 재발송하세요.

비용 영향

이 에러는 요청이 처리되지 않았으므로 비용이 청구되지 않습니다. 단, 잘못된 모델로 요청을 반복하다가 다른 에러가 발생할 수 있으니 모니터링이 필요합니다.

자세한 비용 절감 패턴은 Claude API Cost and Prompt Caching Break-Even 또는 무료 비용 계산기를 참고하세요.

자주 묻는 질문

prompt_too_long 에러가 떴을 때 비용이 청구되나요?

처리되지 않은 요청이므로 청구되지 않습니다. 단, 무한 재시도 루프는 다른 에러로 비용을 발생시킬 수 있습니다.

prompt_too_long와 다른 에러의 차이는?

prompt_too_long는 클라이언트 측 문제로 요청 수정 없이는 재시도해도 같은 결과입니다. 5xx 에러 (500/529)는 일시적 서버 이슈라 재시도가 효과적입니다.

Bedrock/Vertex에서도 같은 에러 코드인가요?

네, Anthropic의 error.type 명명 규칙은 모든 deployment (Direct API, AWS Bedrock, GCP Vertex AI)에서 동일합니다. 다만 HTTP 상태 코드는 platform 별로 wrapping되어 다를 수 있습니다 (예: Bedrock은 에러 type을 다른 prefix로 변경).

다음 단계

프로덕션 코드에 retry 로직을 추가하려면 Production Patterns for Claude Agents를
비용을 모니터링하려면 Claude API 비용 모니터링 가이드를
에러 분류 자동화는 무료 /cheatsheet-한국어에서 30개 프롬프트로

Claude API model_not_found (not_found_error): 원인과 해결법

Sangmin Lee — Sun, 05 Jul 2026 01:30:01 +0000

Originally published at claudeguide.io/claude-api-error-model-not-found

Claude API model_not_found (not_found_error): 원인과 해결법

Claude API model_not_found not_found_error는 지정한 model 문자열이 존재하지 않거나 deprecated된 경우에 발생합니다 (2026 기준). 모델 이름 오류이며, 재시도하지 말고 요청 자체를 수정해야 합니다. 이 글은 5가지 흔한 원인과 Python/TypeScript 코드 예시를 다룹니다.

전반적인 Claude API 에러 처리 패턴은 Claude API Error Handling 가이드를 참고하세요.

무엇을 의미하는가?

model_not_found 에러 서브타입는 지정한 model 문자열이 존재하지 않거나 deprecated된 경우을 의미합니다. Anthropic API의 에러 응답 본문에는 error.type이 "not_found_error"로 명시되며, error.message에 구체적 사유가 옵니다.

응답 예시:

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "..."
  }
}

흔한 원인 5가지

오타 (예: claude-sonnet-4 → 정답: claude-sonnet-4-5)
Deprecated 모델 사용 (claude-2.0, claude-instant-1.2)
Legacy 형식 (claude-sonnet-4-5-20240229) — 신형식 권장
Bedrock 사용 시 region에 미배포된 모델

해결 코드 (Python)

VALID_MODELS = {
    "claude-haiku-4-5", "claude-sonnet-4-5", "claude-opus-4-5",
    # Add aliases as Anthropic releases them
}

def validate_model(model: str):
    if model not in VALID_MODELS:
        raise ValueError(
            f"{model} not in valid set. Use one of: {VALID_MODELS}"
        )

해결 코드 (TypeScript)

const VALID_MODELS = new Set([
  "claude-haiku-4-5",
  "claude-sonnet-4-5",
  "claude-opus-4-5",
]);

function validateModel(model: string): void {
  if (!VALID_MODELS.has(model)) {
    throw new Error(`${model} invalid`);
  }
}

구버전 모델 마이그레이션 가이드

기존 코드에서 deprecated 모델 이름을 사용하고 있다면 다음 매핑으로 교체하세요:

구버전 (deprecated)	신버전 (2026)	비고
`claude-2.0`	`claude-sonnet-4-5`	범용 대체
`claude-2.1`	`claude-sonnet-4-5`	범용 대체
`claude-instant-1.2`	`claude-haiku-4-5`	빠른 처리 대체
`claude-3-haiku-20240307`	`claude-haiku-4-5`	Haiku 세대 업그레이드
`claude-3-5-sonnet-20241022`	`claude-sonnet-4-5`	Sonnet 세대 업그레이드
`claude-3-opus-20240229`	`claude-opus-4`	Opus 세대 업그레이드

코드베이스 전체 마이그레이션:

# 구버전 모델 이름을 일괄 검색
grep -r "claude-2\|claude-3\|claude-instant" ./src --include="*.py" --include="*.ts"

# 발견된 파일에서 모델 이름을 상수로 분리한 뒤 중앙 관리

모델 이름을 코드 전체에 하드코딩하면 Anthropic이 새 모델을 출시할 때마다 여러 파일을 수정해야 합니다. MODEL_REGISTRY 딕셔너리나 환경변수(CLAUDE_MODEL=claude-sonnet-4-5)로 중앙 관리하면 한 곳만 수정하면 됩니다.

재시도하지 마세요

이 에러는 클라이언트 측 문제라 재시도해도 같은 결과입니다. 위 원인을 확인하고 요청을 수정한 뒤 재발송하세요.

비용 영향

자세한 비용 절감 패턴은 Claude API Cost and Prompt Caching Break-Even 또는 무료 비용 계산기를 참고하세요.

2026 Claude 모델 이름 레지스트리

다음 표는 2026년 기준 유효한 모델 이름 목록입니다. 이 외의 문자열은 model_not_found를 유발합니다:

모델 이름	용도	컨텍스트 윈도우
`claude-haiku-4-5`	빠른 처리, 분류, 간단한 Q&A	200K
`claude-sonnet-4-5`	범용 고성능	200K / 1M (확장)
`claude-opus-4`	복잡한 추론, 전략	200K
`claude-haiku-4-5-20250514`	haiku-4-5 고정 버전	200K
`claude-sonnet-4-5-20250514`	sonnet-4-5 고정 버전	200K

자주 틀리는 이름 패턴:

claude-sonnet-4 (틀림) → claude-sonnet-4-5 (정답)
claude-3-5-sonnet (틀림, 구버전) → claude-sonnet-4-5 (신버전)
claude-opus-4-5 (틀림) → claude-opus-4 (정답)
claude-4-sonnet (틀림) → claude-sonnet-4-5 (정답)

빠른 진단 체크리스트

모델 이름 오류를 빠르게 찾는 체크리스트:

[ ] 모델 이름이 위 레지스트리 테이블과 정확히 일치하는가?
[ ] 코드에서 하드코딩된 모델 이름을 상수로 관리하고 있는가? (분산된 하드코딩 → 오타 위험)
[ ] VALID_MODELS 세트에서 사전 검증 후 API를 호출하고 있는가?
[ ] 구버전 모델(claude-2.0, claude-instant-1.2)에서 마이그레이션됐는가?
[ ] AWS Bedrock 사용 시 모델 이름 대신 ARN(arn:aws:bedrock:...)을 사용하는가?

프로덕션 모니터링

모델 이름은 배포 시 고정되므로, 코드 배포 직후 모델 유효성을 사전 검증하는 패턴이 효과적입니다:

import anthropic, logging

logger = logging.getLogger("claude.model")

# 2026 유효 모델 집합 — 신규 모델 출시 시 업데이트
VALID_MODELS = {
    "claude-haiku-4-5",
    "claude-sonnet-4-5",
    "claude-opus-4",
    "claude-haiku-4-5-20250514",
    "claude-sonnet-4-5-20250514",
}

def safe_create(client: anthropic.Anthropic, model: str, **kwargs):
    if model not in VALID_MODELS:
        logger.error(
            "model_not_found — 배포 전 모델 이름 점검 필요",
            extra={
                "requested_model": model,
                "valid_models": list(VALID_MODELS),
            }
        )
        raise ValueError(
            f"'{model}'은 유효하지 않은 모델입니다. "
            f"사용 가능: {sorted(VALID_MODELS)}"
        )
    return client.messages.create(model=model, **kwargs)

언제 지원팀에 연락해야 하나요?

model_not_found는 항상 클라이언트 코드 수정으로 해결됩니다. 다음 경우에만 support.anthropic.com에 문의하세요:

[ ] Anthropic 문서에 명시된 이름을 정확히 사용했는데 not_found_error가 반환되는 경우
[ ] Bedrock에서 특정 리전에서만 모델을 찾지 못하는 경우 (리전 배포 확인 필요)
[ ] 이전에 정상 동작하던 모델 이름이 갑자기 not_found를 반환하는 경우 (deprecated 가능성 → 공식 마이그레이션 가이드 요청)

자주 묻는 질문

model_not_found 에러가 떴을 때 비용이 청구되나요?

처리되지 않은 요청이므로 청구되지 않습니다. 단, 무한 재시도 루프는 다른 에러로 비용을 발생시킬 수 있습니다.

model_not_found와 다른 에러의 차이는?

model_not_found는 클라이언트 측 문제로 요청 수정 없이는 재시도해도 같은 결과입니다. 5xx 에러 (500/529)는 일시적 서버 이슈라 재시도가 효과적입니다.

Bedrock/Vertex에서도 같은 에러 코드인가요?

다음 단계

프로덕션 코드에 retry 로직을 추가하려면 Production Patterns for Claude Agents를
비용을 모니터링하려면 Claude API 비용 모니터링 가이드를
에러 분류 자동화는 무료 /cheatsheet-한국어에서 30개 프롬프트로

Claude API max_tokens (invalid_request_error): 원인과 해결법

Sangmin Lee — Sat, 04 Jul 2026 01:31:33 +0000

Originally published at claudeguide.io/claude-api-error-max-tokens

Claude API max_tokens (invalid_request_error): 원인과 해결법

Claude API max_tokens invalid_request_error는 max_tokens가 모델별 출력 한도를 초과한 경우에 발생합니다 (2026 기준). max_tokens 한도 초과이며, 재시도하지 말고 요청 자체를 수정해야 합니다. 이 글은 5가지 흔한 원인과 Python/TypeScript 코드 예시를 다룹니다.

전반적인 Claude API 에러 처리 패턴은 Claude API Error Handling 가이드를 참고하세요.

무엇을 의미하는가?

max_tokens 에러 서브타입는 max_tokens가 모델별 출력 한도를 초과한 경우을 의미합니다. Anthropic API의 에러 응답 본문에는 error.type이 "invalid_request_error"로 명시되며, error.message에 구체적 사유가 옵니다.

응답 예시:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "..."
  }
}

흔한 원인 5가지

Sonnet 4.5: max_tokens 8192 한도
Opus 4.5: max_tokens 8192 한도
Haiku 4.5: max_tokens 8192 한도
Sonnet extended thinking 시: 64K (별도 옵션)
오래된 모델 (Sonnet 3.5)에 대해 새 한도 사용

해결 코드 (Python)


python
MAX_OUTPUT = {
    "claude-haiku-4-5": 8192,
    "claude-sonnet-4-5": 8192,
    "claude-opus-4-5": 8192,
}

def safe_max_tokens(model: str, requested: int) -

Claude API invalid_api_key (authentication_error): 원인과 해결법

Sangmin Lee — Sat, 04 Jul 2026 01:30:50 +0000

Originally published at claudeguide.io/claude-api-error-invalid-api-key

Claude API invalid_api_key (authentication_error): 원인과 해결법

Claude API invalid_api_key authentication_error는 API key 문자열 자체가 손상되었거나 형식이 맞지 않는 경우에 발생합니다 (2026 기준). 잘못된 API key 형식이며, 재시도하지 말고 요청 자체를 수정해야 합니다. 이 글은 5가지 흔한 원인과 Python/TypeScript 코드 예시를 다룹니다.

전반적인 Claude API 에러 처리 패턴은 Claude API Error Handling 가이드를 참고하세요.

무엇을 의미하는가?

invalid_api_key 에러 서브타입는 API key 문자열 자체가 손상되었거나 형식이 맞지 않는 경우을 의미합니다. Anthropic API의 에러 응답 본문에는 error.type이 "authentication_error"로 명시되며, error.message에 구체적 사유가 옵니다.

응답 예시:

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "..."
  }
}

흔한 원인 5가지

환경변수 설정 시 따옴표 포함 (예: ANTHROPIC_API_KEY="sk-ant-...")
key 끝의 줄바꿈 문자 (echo 명령으로 echo $key | xxd 확인)
다른 LLM provider key를 잘못 사용 (OpenAI sk-xxx 등)

해결 코드 (Python)

import os
api_key = os.environ.get("ANTHROPIC_API_KEY", "").strip()
# Strip quotes if accidentally wrapped
api_key = api_key.strip('"').strip("'")
if not api_key.startswith("sk-ant-"):
    raise RuntimeError(f"Invalid format: {api_key[:10]}...")

해결 코드 (TypeScript)

const apiKey = (process.env.ANTHROPIC_API_KEY ?? "")
  .trim()
  .replace(/^["']|["']$/g, "");
if (!apiKey.startsWith("sk-ant-")) {
  throw new Error(`Invalid format: ${apiKey.slice(0, 10)}...`);
}

환경별 API Key 설정 방법

로컬 개발 환경 (.env 파일)

# .env 파일 — 따옴표 없이 설정
ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxx...

# 읽기 전용 모드로 설정 (선택 사항)
chmod 600 .env

Docker 환경

# Dockerfile에 key를 하드코딩하지 말 것
# docker run -e ANTHROPIC_API_KEY=sk-ant-... 또는
# docker-compose.yml의 environment 섹션에서 host 환경변수 참조:
# environment:
#   - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}

GitHub Actions / CI 환경
Repository Settings → Secrets and variables → Actions → "New repository secret"에 ANTHROPIC_API_KEY를 추가하고, workflow 파일에서 ${{ secrets.ANTHROPIC_API_KEY }}로 참조합니다. Secrets는 로그에서 자동으로 마스킹됩니다.

Vercel / Netlify 환경
대시보드 → Environment Variables에서 ANTHROPIC_API_KEY를 추가한 다음 반드시 재배포를 실행해야 변경사항이 적용됩니다. 빌드 시점과 런타임 모두에 설정이 필요한 경우 "Exposed to browser"는 비활성화 상태로 유지하세요.

재시도하지 마세요

이 에러는 클라이언트 측 문제라 재시도해도 같은 결과입니다. 위 원인을 확인하고 요청을 수정한 뒤 재발송하세요.

비용 영향

자세한 비용 절감 패턴은 Claude API Cost and Prompt Caching Break-Even 또는 무료 비용 계산기를 참고하세요.

invalid_api_key vs authentication_error 차이

invalid_api_key는 authentication_error 타입의 하위 케이스입니다. error.message 필드에 "invalid x-api-key" 또는 "invalid API key" 같은 문구가 포함되어 있으면 키 형식 또는 만료 문제로 좁힐 수 있습니다. 반면 authentication_error가 발생하지만 메시지에 key 관련 내용이 없다면 조직(Organization) 계정 문제이거나 서비스 인증 설정 오류일 수 있습니다.

에러 구분 코드:

import anthropic

def handle_auth_error(e: anthropic.AuthenticationError):
    msg = str(e).lower()
    if "api key" in msg or "x-api-key" in msg:
        print("API key 형식 또는 만료 문제 — key 재발급")
    elif "organization" in msg:
        print("조직 계정 문제 — Console에서 조직 상태 확인")
    else:
        print(f"인증 문제 (기타): {e}")

빠른 진단 체크리스트

API key 형식 문제를 단계별로 찾아내는 체크리스트:

[ ] key가 sk-ant-api03-로 시작하는가? (sk-ant-만 있고 api03- 없으면 구버전 key)
[ ] 환경변수 설정 시 따옴표로 감싸지 않았는가? (KEY="value" 형식은 따옴표가 값에 포함됨)
[ ] printenv ANTHROPIC_API_KEY | wc -c 명령으로 예상 문자 수(약 108자)와 일치하는가?
[ ] printenv ANTHROPIC_API_KEY | xxd | tail -1 로 마지막 바이트가 0a (줄바꿈)인지 확인했는가?
[ ] Docker/K8s 환경이라면 Secret이 올바르게 마운트됐는가?

프로덕션 모니터링

key 형식 검증은 애플리케이션 시작 시점에 한 번만 수행하는 것이 효율적입니다. 런타임 중에 key 손상을 감지하는 패턴:


python
import re, os, logging

logger = logging.getLogger("claude.key")

# Anthropic API key 정규식 패턴 (2026 기준)
_KEY_PATTERN = re.compile(r"^sk-ant-api\d{2}-[A-Za-z0-9_\-]{95,}$")

def validate_api_key(key: str) -

Claude API file_upload_error (invalid_request_error): 원인과 해결법

Sangmin Lee — Sat, 04 Jul 2026 01:30:47 +0000

Originally published at claudeguide.io/claude-api-error-file-upload-error

Claude API file_upload_error (invalid_request_error): 원인과 해결법

Claude API file_upload_error invalid_request_error는 Files API에 파일 업로드 시 형식/크기/MIME-type 오류에 발생합니다 (2026 기준). Files API 업로드 실패이며, 재시도하지 말고 요청 자체를 수정해야 합니다. 이 글은 5가지 흔한 원인과 Python/TypeScript 코드 예시를 다룹니다.

전반적인 Claude API 에러 처리 패턴은 Claude API Error Handling 가이드를 참고하세요.

무엇을 의미하는가?

file_upload_error 에러 서브타입는 Files API에 파일 업로드 시 형식/크기/MIME-type 오류을 의미합니다. Anthropic API의 에러 응답 본문에는 error.type이 "invalid_request_error"로 명시되며, error.message에 구체적 사유가 옵니다.

응답 예시:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "..."
  }
}

흔한 원인 5가지

파일이 32MB 초과 (Files API 한도)
MIME type이 application/pdf, image/* 외
Beta 헤더 누락 (anthropic-beta: files-api-2025-04-14)
Files API 미사용 region (Bedrock 일부 region)

해결 코드 (Python)

# Use Files API for large attachments
import anthropic

client = anthropic.Anthropic(default_headers={
    "anthropic-beta": "files-api-2025-04-14"
})

with open("doc.pdf", "rb") as f:
    file = client.files.create(file=f)
print(f"File ID: {file.id}")  # use in messages.create

response = client.messages.create(
    model="claude-sonnet-4-5", max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {"type": "document", "source": {"type": "file", "file_id": file.id}},
            {"type": "text", "text": "Summarize"},
        ],
    }],
)

해결 코드 (TypeScript)

const file = await client.files.create({
  file: fs.createReadStream("doc.pdf"),
});
const response = await client.messages.create({
  model: "claude-sonnet-4-5",
  max_tokens: 1024,
  messages: [{
    role: "user",
    content: [
      { type: "document", source: { type: "file", file_id: file.id } },
      { type: "text", text: "Summarize" },
    ],
  }],
}, { headers: { "anthropic-beta": "files-api-2025-04-14" } });

재시도하지 마세요

이 에러는 클라이언트 측 문제라 재시도해도 같은 결과입니다. 위 원인을 확인하고 요청을 수정한 뒤 재발송하세요.

비용 영향

자세한 비용 절감 패턴은 Claude API Cost and Prompt Caching Break-Even 또는 무료 비용 계산기를 참고하세요.

자주 묻는 질문

file_upload_error 에러가 떴을 때 비용이 청구되나요?

처리되지 않은 요청이므로 청구되지 않습니다. 단, 무한 재시도 루프는 다른 에러로 비용을 발생시킬 수 있습니다.

file_upload_error와 다른 에러의 차이는?

file_upload_error는 클라이언트 측 문제로 요청 수정 없이는 재시도해도 같은 결과입니다. 5xx 에러 (500/529)는 일시적 서버 이슈라 재시도가 효과적입니다.

Bedrock/Vertex에서도 같은 에러 코드인가요?

다음 단계

프로덕션 코드에 retry 로직을 추가하려면 Production Patterns for Claude Agents를
비용을 모니터링하려면 Claude API 비용 모니터링 가이드를
에러 분류 자동화는 무료 /cheatsheet-한국어에서 30개 프롬프트로

Claude API context_length_exceeded (invalid_request_error): 원인과 해결법

Sangmin Lee — Sat, 04 Jul 2026 01:30:03 +0000

Originally published at claudeguide.io/claude-api-error-context-length-exceeded

Claude API context_length_exceeded (invalid_request_error): 원인과 해결법

Claude API context_length_exceeded invalid_request_error는 messages 누적 토큰 + max_tokens가 모델의 context window 초과에 발생합니다 (2026 기준). 컨텍스트 길이 초과이며, 재시도하지 말고 요청 자체를 수정해야 합니다. 이 글은 5가지 흔한 원인과 Python/TypeScript 코드 예시를 다룹니다.

전반적인 Claude API 에러 처리 패턴은 Claude API Error Handling 가이드를 참고하세요.

무엇을 의미하는가?

context_length_exceeded 에러 서브타입는 messages 누적 토큰 + max_tokens가 모델의 context window 초과을 의미합니다. Anthropic API의 에러 응답 본문에는 error.type이 "invalid_request_error"로 명시되며, error.message에 구체적 사유가 옵니다.

응답 예시:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "..."
  }
}

흔한 원인 5가지

Sonnet 4.5 1M context를 사용 중인데 max_tokens가 1M-요청토큰보다 큼
긴 system prompt + 누적된 conversation history
PDF/document 첨부의 token 사용량 미고려
Tool result가 messages에 누적되어 폭증

해결 코드 (Python)


python
import anthropic

# Pre-compute token usage with the count_tokens endpoint
client = anthropic.Anthropic()
response = client.messages.count_tokens(
    model="claude-sonnet-4-5",
    messages=conversation_history,
    system="You are a helpful assistant.",
)
input_tokens = response.input_tokens
context_window = 200_000  # or 1_000_000 for Sonnet 4.5 1M context
budget = context_window - input_tokens

if budget < 1024:
    # Trim conversation: drop oldest messages
    while budget < 4096 and len(conversation_history)

Claude API cache_error (invalid_request_error): 원인과 해결법

Sangmin Lee — Sat, 04 Jul 2026 01:30:01 +0000

Originally published at claudeguide.io/claude-api-error-cache-error

Claude API cache_error (invalid_request_error): 원인과 해결법

Claude API cache_error invalid_request_error는 cache_control 사용 시 형식 또는 위치 오류에 발생합니다 (2026 기준). Prompt Caching 오류이며, 재시도하지 말고 요청 자체를 수정해야 합니다. 이 글은 5가지 흔한 원인과 Python/TypeScript 코드 예시를 다룹니다.

전반적인 Claude API 에러 처리 패턴은 Claude API Error Handling 가이드를 참고하세요.

무엇을 의미하는가?

cache_error 에러 서브타입는 cache_control 사용 시 형식 또는 위치 오류을 의미합니다. Anthropic API의 에러 응답 본문에는 error.type이 "invalid_request_error"로 명시되며, error.message에 구체적 사유가 옵니다.

응답 예시:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "..."
  }
}

흔한 원인 5가지

cache_control이 messages 배열의 4번째 break-point 초과
ephemeral 외 type 사용 (현재 ephemeral만 지원)
cache_control을 system 또는 messages 외에 적용
TTL 미지원 (자동 5분 만료)

해결 코드 (Python)

# Cache static prefix (system + few-shot examples)
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": LONG_STATIC_INSTRUCTION,  # 1000+ tokens
            "cache_control": {"type": "ephemeral"},  # cache this
        }
    ],
    messages=messages,
)
# Reuse within 5 minutes for 90% cost savings on cached portion

해결 코드 (TypeScript)

const response = await client.messages.create({
  model: "claude-sonnet-4-5",
  max_tokens: 1024,
  system: [{
    type: "text",
    text: LONG_STATIC_INSTRUCTION,
    cache_control: { type: "ephemeral" },
  }],
  messages,
});

재시도하지 마세요

이 에러는 클라이언트 측 문제라 재시도해도 같은 결과입니다. 위 원인을 확인하고 요청을 수정한 뒤 재발송하세요.

비용 영향

자세한 비용 절감 패턴은 Claude API Cost and Prompt Caching Break-Even 또는 무료 비용 계산기를 참고하세요.

자주 묻는 질문

cache_error 에러가 떴을 때 비용이 청구되나요?

처리되지 않은 요청이므로 청구되지 않습니다. 단, 무한 재시도 루프는 다른 에러로 비용을 발생시킬 수 있습니다.

cache_error와 다른 에러의 차이는?

cache_error는 클라이언트 측 문제로 요청 수정 없이는 재시도해도 같은 결과입니다. 5xx 에러 (500/529)는 일시적 서버 이슈라 재시도가 효과적입니다.

Bedrock/Vertex에서도 같은 에러 코드인가요?

다음 단계

프로덕션 코드에 retry 로직을 추가하려면 Production Patterns for Claude Agents를
비용을 모니터링하려면 Claude API 비용 모니터링 가이드를
에러 분류 자동화는 무료 /cheatsheet-한국어에서 30개 프롬프트로

Claude API billing_error (permission_error): 원인과 해결법

Sangmin Lee — Fri, 03 Jul 2026 01:31:38 +0000

Originally published at claudeguide.io/claude-api-error-billing-error

Claude API billing_error (permission_error): 원인과 해결법

Claude API billing_error permission_error는 조직의 결제 정보 만료, 크레딧 부족, 또는 계정 정지 시에 발생합니다 (2026 기준). 결제/크레딧 부족이며, 재시도하지 말고 요청 자체를 수정해야 합니다. 이 글은 5가지 흔한 원인과 Python/TypeScript 코드 예시를 다룹니다.

전반적인 Claude API 에러 처리 패턴은 Claude API Error Handling 가이드를 참고하세요.

무엇을 의미하는가?

billing_error 에러 서브타입는 조직의 결제 정보 만료, 크레딧 부족, 또는 계정 정지 시을 의미합니다. Anthropic API의 에러 응답 본문에는 error.type이 "permission_error"로 명시되며, error.message에 구체적 사유가 옵니다.

응답 예시:

{
  "type": "error",
  "error": {
    "type": "permission_error",
    "message": "..."
  }
}

흔한 원인 5가지

선불 크레딧 잔액 0 (Console → Billing 확인)
신용카드 만료/거절 (자동 충전 실패)
Anthropic 약관 위반으로 일시 정지
조직 admin이 spending limit을 0으로 설정

해결 코드 (Python)

# Detect billing errors and surface to ops, not retry
import anthropic

try:
    response = client.messages.create(...)
except anthropic.PermissionDeniedError as e:
    if "billing" in str(e).lower() or "credit" in str(e).lower():
        # Alert ops/finance — do NOT retry
        notify_ops("Anthropic billing issue: " + str(e))
        raise BillingError("Top up credits at console.anthropic.com")
    raise

해결 코드 (TypeScript)

try {
  const response = await client.messages.create(opts);
} catch (e: any) {
  if (e.status === 403 && /billing|credit/i.test(e.message ?? "")) {
    await notifyOps(`Billing issue: ${e.message}`);
    throw new BillingError("Top up at console.anthropic.com");
  }
  throw e;
}

재시도하지 마세요

이 에러는 클라이언트 측 문제라 재시도해도 같은 결과입니다. 위 원인을 확인하고 요청을 수정한 뒤 재발송하세요.

비용 영향

자세한 비용 절감 패턴은 Claude API Cost and Prompt Caching Break-Even 또는 무료 비용 계산기를 참고하세요.

자주 묻는 질문

billing_error 에러가 떴을 때 비용이 청구되나요?

처리되지 않은 요청이므로 청구되지 않습니다. 단, 무한 재시도 루프는 다른 에러로 비용을 발생시킬 수 있습니다.

billing_error와 다른 에러의 차이는?

billing_error는 클라이언트 측 문제로 요청 수정 없이는 재시도해도 같은 결과입니다. 5xx 에러 (500/529)는 일시적 서버 이슈라 재시도가 효과적입니다.

Bedrock/Vertex에서도 같은 에러 코드인가요?

다음 단계

프로덕션 코드에 retry 로직을 추가하려면 Production Patterns for Claude Agents를
비용을 모니터링하려면 Claude API 비용 모니터링 가이드를
에러 분류 자동화는 무료 /cheatsheet-한국어에서 30개 프롬프트로

Claude API batch_error (invalid_request_error): 원인과 해결법

Sangmin Lee — Fri, 03 Jul 2026 01:30:53 +0000

Originally published at claudeguide.io/claude-api-error-batch-error

Claude API batch_error (invalid_request_error): 원인과 해결법

Claude API batch_error invalid_request_error는 Batch API job 생성/조회/cancellation 시 형식 오류에 발생합니다 (2026 기준). Batch API 요청 오류이며, 재시도하지 말고 요청 자체를 수정해야 합니다. 이 글은 5가지 흔한 원인과 Python/TypeScript 코드 예시를 다룹니다.

전반적인 Claude API 에러 처리 패턴은 Claude API Error Handling 가이드를 참고하세요.

무엇을 의미하는가?

batch_error 에러 서브타입는 Batch API job 생성/조회/cancellation 시 형식 오류을 의미합니다. Anthropic API의 에러 응답 본문에는 error.type이 "invalid_request_error"로 명시되며, error.message에 구체적 사유가 옵니다.

응답 예시:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "..."
  }
}

흔한 원인 5가지

Batch당 10,000+ requests (한도 초과)
단일 batch 250MB 이상
Custom_id 중복 (각 request 고유해야 함)
29일 만료된 batch_id 조회 시도

해결 코드 (Python)


python
# Validate batch before submission
def validate_batch(requests: list[dict]):
    if len(requests)

DEV Community: Sangmin Lee

Claude API vision_error (invalid_request_error): 원인과 해결법

Claude API vision_error (invalid_request_error): 원인과 해결법

무엇을 의미하는가?

흔한 원인 5가지

해결 코드 (Python)

Claude API tool_use_error (invalid_request_error): 원인과 해결법

Claude API tool_use_error (invalid_request_error): 원인과 해결법

무엇을 의미하는가?

흔한 원인 5가지

해결 코드 (Python)

해결 코드 (TypeScript)

Claude API streaming_error (api_error): 원인과 해결법

Claude API streaming_error (api_error): 원인과 해결법

무엇을 의미하는가?

흔한 원인 5가지

Claude API prompt_too_long (invalid_request_error): 원인과 해결법

Claude API prompt_too_long (invalid_request_error): 원인과 해결법

무엇을 의미하는가?

흔한 원인 5가지

해결 코드 (Python)

해결 코드 (TypeScript)

재시도하지 마세요

비용 영향

관련 에러

자주 묻는 질문

prompt_too_long 에러가 떴을 때 비용이 청구되나요?

prompt_too_long와 다른 에러의 차이는?

Bedrock/Vertex에서도 같은 에러 코드인가요?

다음 단계

Claude API model_not_found (not_found_error): 원인과 해결법

Claude API model_not_found (not_found_error): 원인과 해결법

무엇을 의미하는가?

흔한 원인 5가지

해결 코드 (Python)

해결 코드 (TypeScript)

구버전 모델 마이그레이션 가이드

재시도하지 마세요

비용 영향

2026 Claude 모델 이름 레지스트리

빠른 진단 체크리스트

프로덕션 모니터링

언제 지원팀에 연락해야 하나요?

관련 에러

자주 묻는 질문

model_not_found 에러가 떴을 때 비용이 청구되나요?

model_not_found와 다른 에러의 차이는?

Bedrock/Vertex에서도 같은 에러 코드인가요?

다음 단계

Claude API max_tokens (invalid_request_error): 원인과 해결법

Claude API max_tokens (invalid_request_error): 원인과 해결법

무엇을 의미하는가?

흔한 원인 5가지

해결 코드 (Python)

Claude API invalid_api_key (authentication_error): 원인과 해결법

Claude API invalid_api_key (authentication_error): 원인과 해결법

무엇을 의미하는가?

흔한 원인 5가지

해결 코드 (Python)

해결 코드 (TypeScript)

환경별 API Key 설정 방법

재시도하지 마세요

비용 영향

invalid_api_key vs authentication_error 차이

빠른 진단 체크리스트

프로덕션 모니터링

Claude API file_upload_error (invalid_request_error): 원인과 해결법

Claude API file_upload_error (invalid_request_error): 원인과 해결법

무엇을 의미하는가?

흔한 원인 5가지

해결 코드 (Python)

해결 코드 (TypeScript)

재시도하지 마세요

비용 영향

관련 에러

자주 묻는 질문

file_upload_error 에러가 떴을 때 비용이 청구되나요?

file_upload_error와 다른 에러의 차이는?

Bedrock/Vertex에서도 같은 에러 코드인가요?

다음 단계