Claude Opus 5.5 API 첫 요청과 400 오류 해결 방법
BetterToken API Key로 Claude Opus 5.5 최소 요청을 보내고 Model ID, max_tokens, thinking, tool_choice와 관련된 400 오류를 단계별로 진단합니다.
목차
유효한 API Key가 있어도 Claude Opus 5.5 첫 호출에서 400 Bad Request가 발생할 수 있습니다. 정확한 Model ID, max_tokens 같은 Messages API 필수 필드, thinking 설정과 tool_choice를 확인하세요. max_tokens 누락은 Messages의 일반적인 검증 오류이지 Opus 5.5에서 새로 생긴 제한이 아닙니다. 모델별 이전 변경에는 thinking과 강제 도구 선택 규칙이 포함됩니다.
이 글은 최소 요청을 보낸 뒤 400 오류를 순서대로 분리합니다. 필수 필드는 Messages API 참조 문서에서, Opus 5.5 고유 변경은 Anthropic 이전 가이드에서 확인하세요. 아래 최소 요청으로 현재 연결과 모델 경로를 한 번 확인하고, 실패하면 반환된 오류 본문에 따라 점검합니다. BetterToken을 통해 claude-opus-5-5를 호출하기 전에는 게시일 또는 배포일에 정확한 Model ID가 현재 카탈로그에 있는지도 확인하세요.
1. API Key, Base URL, Model ID를 먼저 확인합니다
첫 요청에는 본인의 BetterToken API Key, Anthropic-compatible Base URL, 현재 이용 가능한 Model ID 세 가지만 필요합니다.
- BetterToken Workspace에 로그인해 본인 계정에서 API Key를 만듭니다. Secret Manager나 로컬 환경 파일에 저장하고 Git 또는 지원 메시지에 넣지 마세요.
- 현재 모델 및 가격 카탈로그를 열어 정확한 ID
claude-opus-5-5가 제공되는지 확인합니다. Anthropic은 날짜 접미사가 없는 고정 ID로 정의하지만 BetterToken의 제공 상태와 가격은 동적입니다. - Key를 애플리케이션 코드에 직접 쓰지 말고 환경 변수로 전달합니다.
API Key를 만들려면 본인의 BetterToken 계정이 필요합니다. BetterToken 계정 만들기
화면에서의 작업 순서는 BetterToken Quickstart를 참고하세요.
2. Base URL에는 /v1을 빼고 직접 HTTP 경로에는 포함합니다
Anthropic SDK의 Base URL은 https://bettertoken.ai이며, 직접 보내는 Messages 요청의 전체 URL은 https://www.bettertoken.ai/v1/messages입니다.
https://bettertoken.ai/messages를 Base URL로 사용하지 말고, SDK가 리소스 경로를 자동으로 붙이는 경우 /v1/messages를 다시 추가하지 마세요. 현재 shell에 세 값을 설정합니다.
read -rs ANTHROPIC_API_KEY && export ANTHROPIC_API_KEY
export ANTHROPIC_BASE_URL="https://bettertoken.ai"
export CLAUDE_MODEL_ID="claude-opus-5-5"먼저 첫 번째 줄만 실행하세요. 터미널이 숨김 입력을 기다리면 그 상태에서 API Key를 입력하거나 붙여넣고 Enter를 누릅니다. 문자는 화면에 표시되지 않습니다. Key는 현재 shell에만 export되고, 기록에는 secret이 아니라 read 명령만 남습니다. Key를 명령줄에 덧붙이지 마세요.
claude-opus-5-5는 Anthropic이 Claude Platform용으로 문서화한 Model ID입니다. 현재 BetterToken 카탈로그에 이 정확한 ID가 없다면 별칭을 추측하지 말고 제공 상태를 확인하세요.
3. 먼저 최소 요청을 보냅니다
첫 테스트에서는 tools, tool_choice, thinking을 제외해 고급 옵션이 기본 연결 문제를 가리지 않게 합니다.
curl --fail-with-body "$ANTHROPIC_BASE_URL/v1/messages" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d "{
\"model\": \"$CLAUDE_MODEL_ID\",
\"max_tokens\": 4096,
\"messages\": [
{\"role\": \"user\", \"content\": \"다음 단어만 답하세요: pong\"}
]
}"이 요청은 정확한 Model ID를 사용하고, 양의 max_tokens를 포함하며, thinking을 생략하고 도구 호출을 강제하지 않습니다. 이 예시는 Anthropic 마이그레이션 예시에도 쓰인 4096을 max_tokens로 설정해 adaptive thinking과 짧은 응답 모두에 더 많은 여유를 둡니다. 이는 진단 시작값일 뿐, 여기서 실측한 보장값이나 운영 권장값이 아닙니다. 운영에서는 예상 응답, effort, 비용, 지연 시간 목표에 맞게 조정하세요.
--fail-with-body는 HTTP 4xx 또는 5xx에서도 응답 본문을 남깁니다. 로그를 공유하기 전에 API Key, 전체 Prompt, 모델 출력과 기타 민감한 값을 제거하세요.
4. content[0]이 항상 text라고 가정하지 않습니다
HTTP 200이고 최상위 type이 message이면 endpoint가 요청을 받아 처리했다는 뜻입니다. 이 짧은 응답 테스트에서는 text block이 있어야 콘텐츠 생성까지 끝났다고 볼 수 있습니다. adaptive thinking과 응답 텍스트가 같은 max_tokens를 사용하므로 유효한 응답도 텍스트가 나오기 전에 한도에 도달할 수 있습니다.
다음을 확인하세요.
- 최상위
type이message이고model이 요청한 모델과 일치합니다. - 짧은 테스트가 정상 종료되면
stop_reason은end_turn이고content배열에type이text인 block이 하나 이상 있습니다. stop_reason이max_tokens이면 응답은 유효하지만 잘린 것입니다.max_tokens를 높여 다시 요청하세요. 높은 effort를 명시했지만 깊은 추론이 필요 없다면 effort를 낮출 수도 있습니다.- text block이 없고
stop_reason도max_tokens가 아니라면, Key나 Base URL을 바꾸기 전에 전체 응답을 보존하고 해당 중단 이유를 진단하세요. 텍스트가 없다는 사실만으로 연결 실패라고 판단하지 않습니다. - parser가 항상
content[0].text를 읽지 않고type으로 block을 선택합니다. usage에 input 및 output Token 수가 있습니다.- BetterToken Dashboard에 예상 시간의 요청이 모델, status, input/output/cache Token, 청구액과 함께 표시됩니다.
응답 구조는 Anthropic 공식 Messages API 문서에 설명되어 있으며, stop_reason 가이드는 잘린 응답의 처리 방법을 설명합니다. Dashboard는 요청과 사용 기록을 대조하는 용도이며, 전체 Prompt나 전체 응답을 항상 저장한다고 설명해서는 안 됩니다.
5. Messages 공통 오류와 Opus 5.5 변경 사항을 확인합니다
요청에 이전 모델 이름이 남아 있습니다
이전 ID 또는 추측한 날짜형 별칭을 claude-opus-5-5로 바꿉니다. Anthropic은 이를 날짜 접미사가 없는 고정 ID로 정의합니다. 클라우드 플랫폼은 자체 ID를 사용할 수 있지만 이 BetterToken Anthropic-compatible 예제에서는 현재 BetterToken 카탈로그의 정확한 ID를 사용해야 합니다.
max_tokens가 없습니다
모든 Messages 요청에 양의 max_tokens를 넣습니다. 필드 누락은 Messages API의 일반적인 검증 오류이며 Opus 5.5 이전 과정에서 새로 생긴 변경 사항이 아닙니다. thinking과 최종 텍스트를 합친 전체 출력의 하드 한도입니다. Smoke test도 둘 다 들어갈 여유가 필요합니다. stop_reason이 max_tokens이면 연결 실패로 보지 말고 한도를 높여 다시 요청하세요.
Payload가 thinking을 끄거나 수동 예산을 설정합니다
가장 간단한 해결책은 thinking 필드 전체를 제거하는 것입니다. Opus 5.5는 항상 adaptive thinking을 사용합니다. Anthropic 마이그레이션 가이드는 아래의 이전 형식이 모두 400으로 거부된다고 설명합니다.
{"thinking": {"type": "disabled"}}{"thinking": {"type": "enabled", "budget_tokens": 10000}}필드를 명시해야 한다면 {"thinking": {"type": "adaptive"}}를 사용합니다. 추론 깊이는 output_config.effort로 조절하며 low, medium, high, xhigh, max를 지원하고 기본값은 medium입니다. 최소 연결 요청에는 두 필드 모두 필요하지 않습니다.
Payload가 tool_choice를 강제합니다
tool_choice에는 {"type": "auto"} 또는 {"type": "none"}만 사용합니다. Opus 5.5는 {"type": "any"}와 {"type": "tool", "name": "..."}를 거부합니다. 도구 워크플로에서는 auto로 선택하게 하고 Prompt에 도구 사용 조건을 적으며 strict tool use를 켜기 전에 각 schema를 검증하세요.
6. 다른 status에서는 설정을 바꾸기 전에 본문을 읽습니다
| Status | 먼저 확인할 항목 | 피할 행동 |
|---|---|---|
400 | 유효한 JSON, model, max_tokens, messages, thinking 설정, tool_choice | 이유 없이 Key를 교체하거나 같은 잘못된 payload 반복 |
401 / 403 | 완전한 Key, 올바른 account 또는 key group, 올바른 Base URL | 전체 Key를 지원팀에 전송 |
404 | 직접 HTTP 호출에 /v1/messages 사용 여부 | /messages를 전체 route로 간주 |
429 | 응답의 대기 지침, 잔액, limit, 요청 기록 | 대기 없이 반복 재시도 |
다른 provider의 오래된 환경 변수가 남아 있다면 다시 설정하기 전에 지웁니다.
unset ANTHROPIC_API_KEY
unset ANTHROPIC_BASE_URL
unset CLAUDE_MODEL_ID수정 후에는 동일한 최소 요청을 반복하세요. 모델, endpoint, Prompt, 고급 파라미터를 동시에 바꾸면 어떤 변경이 문제를 해결했는지 알기 어렵습니다.
7. Anthropic 정가와 BetterToken 현재 가격을 구분합니다
Anthropic의 2026년 9월 22일 출시 페이지는 Claude Platform 가격을 100만 Input Token당 $4, Output Token당 $20, cache reads $0.20, cache writes $5로 안내했습니다. 이는 Anthropic이 공식 공개한 출시 시점 플랫폼 가격입니다. BetterToken 현재 가격은 동적으로 바뀌므로 최신 가격 페이지를 확인하고, 직접 보낸 작은 요청 한 건을 Dashboard 기록과 대조하세요.
Thinking Token은 Output Token으로 과금되고 max_tokens에는 thinking과 최종 텍스트가 모두 포함됩니다. 따라서 thinking을 껐던 이전 설정에서 옮긴 작업은 Prompt가 같아도 output-token 구성이 달라질 수 있습니다. 운영 전 현재 BetterToken 가격 페이지를 확인하고 작은 요청을 Dashboard 기록과 대조하세요.
SDK, streaming 또는 운영 트래픽으로 넘어가기 전에 Model ID, Key 보관 방식, max_tokens 크기, block type 기반 처리, forced tool choice가 없는지, 민감 정보를 제거한 오류 본문을 다시 확인합니다. 다음 단계는 BetterToken API Reference와 Anthropic 공식 Opus 5.5 migration guide를 참고하세요.
