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가지

1. Sonnet 4.5: max_tokens 8192 한도
2. Opus 4.5: max_tokens 8192 한도
3. Haiku 4.5: max_tokens 8192 한도
4. Sonnet extended thinking 시: 64K (별도 옵션)
5. 오래된 모델 (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) -