Claude Code "API Error: bad_response_status_code" — 내부 상태 코드 읽기

이 오류는 호출이 실패했다는 사실과 원인에 대해서는 거의 알려주지 않습니다. 유용한 정보인 상태 코드와 공급업체 메시지는 디버그 플래그 하나로 확인할 수 있으며, 각 상태에는 서로 다른 해결 방법이 있습니다.

오류

terminal

API Error: bad_response_status_code

(no status, no provider message — the wrapper hides both)

원인과 해결 방법 한눈에 보기

원인	해결 방법
내부 상태가 401 / 403인 경우	사용자 지정 base URL에서 자격 증명 또는 헤더가 일치하지 않습니다. 어떤 인증 변수가 설정되어 있는지 확인하세요.
내부 상태가 404인 경우	해당 호스트에서 모델 ID를 알 수 없거나 base URL에 경로 세그먼트가 추가로 포함된 경우입니다.
내부 상태가 402인 경우	게이트웨이 지갑이 비어 있습니다. 충전하세요. 클라이언트 구성에는 문제가 없습니다.
내부 상태가 429 / 529인 경우	속도 제한에 걸렸거나 업스트림이 포화 상태입니다. 재구성하지 말고 백오프를 적용해 재시도하세요.
200 응답인데 JSON이 아닌 본문	캡티브 포털, 기업 프록시 또는 오류 페이지입니다. 상태는 정상이어도 본문은 사용할 수 없을 수 있습니다.

래퍼를 실제 오류로 바꾸기

Claude Code의 디버그 출력에는 요청과 업스트림 응답이 표시됩니다. 이 기능을 켜고 실패하는 호출을 한 번 실행한 뒤 상태 줄을 읽으세요. 이후의 모든 단계는 해당 내용에 따라 달라집니다.

debug.sh

claude --debug 2>&1 | tee claude-debug.log

grep -iE 'status|http/|error' claude-debug.log | head -20

curl로 동일한 호출 재현

도구에서 base URL과 자격 증명을 가져와 요청을 직접 실행하세요. 이를 통해 "호스트가 거부하는지"와 "클라이언트 형식이 잘못되었는지"를 한 번에 구분할 수 있으며, 원시 본문에는 래퍼가 버린 문제 원인이 일반적인 표현으로 표시되는 경우가 많습니다.

reproduce.sh

curl -i "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,
       "messages":[{"role":"user","content":"ping"}]}'

base URL에 후행 경로가 없는지 확인

Claude Code는 자체 `/v1/...` 경로를 추가합니다. 이미 `/v1`로 끝나는 base URL을 사용하면 `/v1/v1/messages`가 생성되고, 모든 호스트는 이를 404로 응답합니다. 이 오류도 다시 bad_response_status_code로 래핑됩니다. 오리진만 설정하세요.

base-url.sh

# Wrong — doubles the version segment
export ANTHROPIC_BASE_URL="https://api.kunavo.com/v1"

# Right — origin only
export ANTHROPIC_BASE_URL="https://api.kunavo.com"

Kunavo를 통해 호출하는 경우

Kunavo에서 즉시 알아야 할 두 상태는 402와 401입니다. 402는 지갑이 요청을 처리할 수 없다는 뜻으로, 구성 문제가 아니라 잔액 문제입니다. 401은 Kunavo가 유효한 sk-kn- 키를 받지 못했다는 뜻입니다. Kunavo는 Authorization: Bearer 또는 x-api-key에서 키를 읽으므로 Claude Code가 실제로 무엇을 전송했는지 확인하세요. ANTHROPIC_API_KEY의 키는 대화형 세션에서 일회성 승인이 필요하며 거부하면 무시되고, ANTHROPIC_AUTH_TOKEN은 즉시 사용됩니다. 두 상태 모두 원인을 설명하는 JSON 본문과 함께 반환되므로 추측이 아닌 디버그 로그로 판단할 수 있습니다. 실패한 요청에는 요금이 청구되지 않습니다. 어떤 변수를 설정해야 하는지와 그 이유는 다음에서 설명합니다 인증 변수 가이드.

자주 묻는 질문

이 오류가 Claude Code 자체의 버그일 수도 있나요?

드뭅니다. 이는 전송 계층 래퍼로, 무언가가 응답했지만 성공 응답이 아니었다는 뜻입니다. curl로 재현하면 확인할 수 있습니다. curl도 실패한다면 클라이언트가 문제는 아닙니다.

공식 API에서는 작동하지만 내 게이트웨이에서는 작동하지 않습니다.

그렇다면 차이는 도구가 아니라 자격 증명 또는 base URL입니다. 게이트웨이가 요구하는 인증 헤더와 base URL에 이미 /v1이 포함되어 있는지 확인하세요.

자동으로 재시도해야 하나요?

상태를 확인한 후에만 재시도하세요. 401 또는 404를 재시도하는 것은 의미가 없고, 429 또는 529는 백오프를 적용해 재시도하는 것이 올바릅니다.