Claude Code 403·503·529 오류, 발생 위치별 해결법

Claude Code에서 API Error: 403이나 503을 봤다면 숫자만으로 원인을 정하지 마세요. 같은 403이라도 회사 프록시가 막았을 수도, Anthropic이 계정 권한을 거부했을 수도, Claude가 읽으려던 웹사이트가 거절했을 수도 있습니다. 503은 Anthropic Messages API의 공식 오류 목록에 아예 없는 코드여서, ANTHROPIC_BASE_URL로 게이트웨이나 API 중계 서비스를 쓰고 있다면 대개 그쪽이 보낸 응답입니다. 의미가 분명한 것은 529 하나로, Anthropic 모델 용량이 일시적으로 가득 찼다는 뜻입니다.

확인 순서는 단순합니다. 오류 원문을 통째로 복사해 두고, Claude Code 안에서 /status를 열어 Anthropic base URL 줄이 있는지 봅니다. 이 줄이 있으면 모든 요청이 그 주소를 먼저 거치므로 게이트웨이·중계 서비스부터, 없으면 Anthropic 계정 권한, 내 네트워크, Anthropic 서비스 상태 순서로 확인합니다. 명령과 메시지 표기는 2026년 9월 29일 기준 Claude Code 공식 문서를 따릅니다.

오류 원문으로 찾는 진단 표

오류 문자열은 화면에 보이는 영어 원문 그대로입니다. "응답한 곳"이 게이트웨이나 중계 서비스로 나오는 줄은 Claude Code를 재설치하거나 다시 로그인해도 풀리지 않습니다.

/status와 오류 끝 문장으로 응답한 곳 가리기

/status를 실행하면 Status 탭이 열립니다. 여기서 두 줄을 봅니다.

• Anthropic base URL: 게이트웨이 주소가 설정됐을 때만 나타납니다. 이 줄이 있으면 요청은 Anthropic보다 이 주소에 먼저 도착하고, 오류도 여기서 만들어졌을 가능성을 먼저 봐야 합니다. 줄이 없으면 Anthropic API로 직접 가거나, CLAUDE_CODE_USE_BEDROCK 같은 설정을 썼다면 해당 클라우드 제공자로 갑니다.
• Auth token 또는 API key: 어떤 변수의 자격 증명이 쓰이는지 알려 줍니다. 대신 Login method 줄에 claude.ai 계정이 보이면 Pro/Max 구독 로그인으로 요청하고 있다는 뜻입니다.

셸에서 export한 변수와 ~/.claude/settings.json의 env 블록이 같은 변수를 동시에 설정하면 설정 파일 값이 적용됩니다. 셸에서 ANTHROPIC_BASE_URL을 지웠는데도 /status에 주소가 계속 보인다면 설정 파일의 env 블록에 남은 값이 원인입니다.

오류 메시지의 마지막 문장도 단서가 됩니다. 현재 Claude Code는 5xx 오류 끝에 상태를 확인할 곳을 적는데, 이 문장이 연결 경로에 따라 달라집니다.

다만 버전에 따라 표시가 다릅니다. 제목 없는 HTML 오류 페이지를 상태 코드와 표준 이름으로 보여 주는 동작은 v2.1.281부터입니다. 2026년 5월 Claude Code 2.1.137에서 보고된 503 No available accounts 오류는 중계 서비스가 보낸 응답인데도 끝 문장이 check status.claude.com이었습니다. claude --version으로 버전을 확인하고, 오래된 버전이라면 끝 문장보다 /status의 base URL 줄을 기준으로 판단하세요.

403: 막힌 것인지, 권한이 없는 것인지

403은 "요청은 도착했지만 거절됐다"는 뜻일 뿐, 누가 거절했는지는 알려 주지 않습니다. 아래 다섯 경우는 해결 방법이 서로 겹치지 않습니다.

Claude가 URL을 가져오다 403이 났을 때

작업 중 Claude가 문서나 웹 페이지를 읽으려다 403으로 실패했다면 거절한 쪽은 그 웹사이트입니다. Reddit의 r/CloudFlare, r/ClaudeAI에 올라온 사례에서는 Cloudflare WAF 규칙이나 봇 차단이 자동화된 요청을 막은 것이 원인이었습니다. 이것은 Claude Code의 API 접근과 무관하므로 로그인이나 API 키를 건드릴 필요가 없습니다. 내 사이트라면 WAF 규칙에서 해당 요청을 허용하고, 남의 사이트라면 필요한 내용을 직접 붙여 넣거나 다른 출처를 쓰는 편이 빠릅니다.

로그인 직후 Request not allowed가 뜰 때

API Error: 403 {"error":{"type":"forbidden","message":"Request not allowed"}}는 Anthropic이 계정 권한을 이유로 거절한 경우입니다. 공식 문서가 안내하는 확인 항목은 로그인 방식별로 다릅니다.

• Claude Pro/Max 구독 로그인: claude.ai/settings에서 구독이 활성 상태인지 확인합니다.
• Anthropic Console 계정: 계정에 "Claude Code" 또는 "Developer" 역할이 있어야 합니다. 관리자가 Console의 Settings → Members에서 부여합니다.
• Claude Enterprise: 로그인 화면에 Claude Code access has not been granted for this account가 뜨면 조직이 역할을 Custom으로 지정했고 그 사용자 지정 역할 중 어느 것도 Claude Code를 허용하지 않는 상태입니다. Claude Code 쪽에서는 바꿀 수 있는 것이 없으므로 조직 Owner에게 역할 변경을 요청하고, 변경 후 claude를 실행해 다시 로그인합니다.

Anthropic 지원 센터의 설치·인증 문제 해결 문서는 계정은 있지만 Claude Code가 요청하는 모델에 대한 접근 권한이 없을 때 모든 요청이 403이나 "모델을 사용할 수 없음"으로 실패하는 경우도 따로 다룹니다. 워크스페이스에서 Claude Code 사용이 켜져 있는지, 해당 모델이 허용돼 있는지는 관리자만 확인할 수 있습니다. Claude API의 403 permission_error 역시 "API 키에 해당 리소스를 쓸 권한이 없다"는 뜻이고, 공식 오류 문서는 Claude Console의 조직 접근 권한과 워크스페이스 설정을 확인하라고 안내합니다.

회사망·프록시 뒤에서 나는 403

같은 셸에서 Anthropic API 호스트에 직접 닿는지 먼저 확인합니다.

curl -I https://api.anthropic.com
# Windows PowerShell
curl.exe -I https://api.anthropic.com

Claude Code 설치 문서는 이런 연결 점검에서 403이 돌아오면 대개 프록시나 네트워크 필터가 호스트를 막고 있거나, 지역 제한에 걸린 경우라고 설명합니다. 회사망이라면 IT 팀에 프록시 주소를 받아 Claude Code를 실행하기 전에 설정합니다.

export HTTPS_PROXY=http://proxy.example.com:8080
# 인증이 필요한 프록시
export HTTPS_PROXY=http://username:password@proxy.example.com:8080

Claude Code는 https_proxy, HTTPS_PROXY, http_proxy, HTTP_PROXY 순서로 처음 설정된 값을 쓰고, NO_PROXY로 예외를 지정할 수 있습니다. SOCKS 프록시는 지원하지 않습니다.

터미널에서는 되는데 VS Code 확장에서만 실패한다면 VS Code가 셸의 환경 변수를 물려받지 못했을 수 있습니다. 공식 문서는 API 키를 예로 들어 터미널에서 code .로 VS Code를 실행하라고 안내하는데, 프록시 변수도 같은 방식으로 전달됩니다. 매번 터미널에서 열기 번거롭다면 확장 설정의 environmentVariables에 넣거나, CLI와 확장이 함께 읽는 ~/.claude/settings.json의 env 블록에 넣습니다. 확장 쪽 증상을 더 좁히려면 Claude Code가 VS Code에서 안 될 때는 먼저 실패 지점을 나눠야 한다를 참고하세요.

curl은 성공하는데 Claude Code만 실패한다면 echo $ANTHROPIC_BASE_URL과 설정 파일의 env 블록을 확인합니다. 예전에 쓰던 게이트웨이 주소가 남아 있으면 모델 요청이 api.anthropic.com이 아닌 그 주소로 갑니다. 403이 아니라 ECONNREFUSED, ECONNRESET 같은 연결 오류라면 Claude Code Unable to connect to API 해결: ECONNREFUSED, ECONNRESET, 프록시 점검이 더 맞습니다.

게이트웨이 앞 WAF가 막은 403

회사가 직접 운영하는 LLM 게이트웨이를 쓰는데 403 Forbidden이라는 HTML 본문이 돌아오고, 정작 게이트웨이 로그에는 요청이 들어온 기록이 없다면 게이트웨이 앞의 웹 방화벽(WAF)이나 리버스 프록시가 요청 본문을 막은 것입니다. Claude Code 요청에는 XML 형식 태그와 소스 코드가 들어 있어 교차 사이트 스크립팅(XSS) 본문 규칙에 걸리기 쉽습니다. 짧은 curl 테스트는 통과하는데 실제 세션만 실패하는 이유가 이것입니다.

관리자는 /v1/messages 경로를 본문 검사에서 제외해야 합니다. 공식 문서가 예로 드는 규칙은 AWS WAF의 CrossSiteScripting_Body, nginx ModSecurity의 OWASP CRS 본문 규칙입니다.

Claude apps gateway로 로그인한 경우에는 Gateway refused the request · signing in again won't change this — check with your gateway administrator · API Error: 403 ...처럼 표시됩니다. 문구 그대로 다시 로그인해도 바뀌지 않으며, API Error: 뒤에 붙은 내용이 게이트웨이가 돌려준 거절 사유입니다. v2.1.273 이전에는 같은 상황에서 Please run /login이나 Failed to authenticate가 떠서 로그인 문제로 오해하기 쉬웠습니다.

일부 서드파티 엔드포인트는 403 {"type":"forbidden","message":"This service is restricted to the official Claude Code client."}를 돌려준다는 보고도 있습니다. Anthropic 문서에는 없는 메시지로, 중계 서비스가 자체적으로 클라이언트를 검사해 거절한 것이므로 해당 서비스 운영자에게 확인해야 합니다.

지역 제한 403

2026년 9월 29일 기준 Anthropic 지원 국가 목록에는 대한민국, 미국, 일본, 대만 등이 들어 있고 중국, 홍콩, 마카오, 러시아는 없습니다. 설치 페이지가 App unavailable in region을 보여 주면 현재 위치가 지원 국가가 아니라는 뜻입니다.

한국에서 이 메시지를 봤다면 회사 VPN이나 프록시의 출구가 다른 나라에 있는지부터 IT 팀에 확인하세요. 실제로 지원되지 않는 지역에 있다면 로컬 설정으로 고칠 수 있는 문제가 아니므로 공식 직결 시도를 멈추는 것이 맞습니다. 위치를 숨겨 제한을 피하는 방식은 계정에 위험이 따릅니다.

~/.claude를 통째로 지우기 전에

rm -rf ~/.claude로 폴더를 지우고 다시 로그인하는 방법은 권하지 않습니다. 이 폴더에는 설정, 대화 기록, 자격 증명이 함께 들어 있습니다. 지워도 지역, 프록시, 계정 역할은 바뀌지 않으므로 위의 원인에는 효과가 없고 설정만 잃습니다. 로그인 정보를 새로 받고 싶다면 /logout 후 /login으로 충분하며, 공식 403 안내에도 폴더 삭제는 없습니다.

503: 공식 오류 목록에 없는 코드

Claude API 공식 오류 목록은 400, 401, 402, 403, 404, 409, 413, 429, 500, 504, 529로 이루어져 있고, 과부하는 503이 아니라 529 overloaded_error로 표시합니다. 목록에 없다고 해서 Anthropic 쪽에서 503이 절대 나오지 않는다는 뜻은 아니지만, /status에 base URL 줄이 있는 상태에서 503을 봤다면 먼저 의심할 곳은 중간의 게이트웨이나 중계 서비스입니다. Claude Code는 서버 오류를 자동으로 여러 번 재시도한 뒤에 메시지를 보여 주므로, 오류가 떴다는 것은 이미 몇 차례 실패했다는 뜻이기도 합니다.

503 뒤에 붙은 문구로 어떤 소프트웨어가 응답했는지 대략 알 수 있습니다.

몇 가지는 원문을 알아 두면 판단이 빨라집니다. 오픈소스 계정 풀 중계인 sub2api의 소스 코드를 보면, 그룹에 계정은 있지만 요청한 모델을 설정한 계정이 없을 때는 503이 아니라 404 model_not_found를 돌려줍니다. 즉 이 소프트웨어 기준으로 No available accounts 503은 "모델 이름이 틀렸다"보다 "지금 쓸 수 있는 계정이 없다"에 가깝습니다. 같은 문구를 쓰는 다른 중계 소프트웨어도 있을 수 있으니 sub2api로 단정하지는 마세요.

no available server는 Traefik 소스 코드에 정의된 오류 문구입니다. Anthropic이 Traefik을 쓴다는 공개 문서는 없으므로, 이 문구는 호출하는 중계 서비스나 자체 게이트웨이의 서비스가 내려가 있거나 재시작 중이라는 신호로 읽는 것이 합리적입니다. no healthy upstream은 Envoy 같은 프록시가 쓰는 표준 문구로, 2025년 Anthropic 서비스에 문제가 있던 시기에 Claude Code 사용자들이 Reddit에 같은 오류를 여러 건 보고했습니다. 그래서 이 문구 하나만으로는 판단이 안 되고 base URL 줄과 장애 공지를 함께 봐야 합니다.

게이트웨이를 직접 호출해 보는 1토큰 테스트

게이트웨이나 중계 서비스 자체가 살아 있는지는 Claude Code를 거치지 않고 확인할 수 있습니다. 셸에 ANTHROPIC_BASE_URL과 ANTHROPIC_AUTH_TOKEN을 export한 상태에서 실행합니다. 설정 파일에만 넣어 둔 값은 이 명령이 읽지 못합니다.

curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

결과는 이렇게 읽습니다.

• {"id":"msg_로 시작하고 content가 있는 JSON: 주소와 자격 증명이 정상입니다. Claude Code에서만 실패한다면 Claude Code 쪽 설정을 봅니다.
• 알 수 없는 모델이라는 오류: 이것도 주소와 자격 증명은 정상이라는 뜻입니다. 게이트웨이가 인증을 통과시킨 뒤 모델 이름을 거절했기 때문입니다.
• 401: 자격 증명이 거절됐습니다. ANTHROPIC_AUTH_TOKEN과 ANTHROPIC_API_KEY 중 서비스가 요구하는 쪽으로 바꿔 봅니다. 서비스가 x-api-key 헤더로 키를 받는다면 Authorization 헤더를 x-api-key: $ANTHROPIC_API_KEY로 바꿉니다.
• Claude Code에서 본 것과 같은 503: 원인은 게이트웨이나 중계 서비스 쪽에 있습니다. Claude Code를 다시 설치해도 결과는 같습니다.

게이트웨이 설정 전반은 Claude Code API 설정: 키, settings.json, 모델, 게이트웨이 확인 순서에 정리돼 있습니다.

529: 내 한도가 아니라 Anthropic 용량 문제

API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary.는 Claude Code가 지수 백오프로 최대 10회 자동 재시도를 마친 뒤에 보여 주는 메시지입니다. 공식 문서 기준으로 529는 내 사용량 한도가 아니고 할당량에서 차감되지도 않습니다. 구독이나 API 키를 점검할 이유가 없다는 점에서 403·503과 갈립니다.

할 일은 세 가지입니다. status.claude.com(또는 메시지가 가리키는 제공자 상태 페이지)에서 용량 공지를 확인하고, 몇 분 뒤 다시 시도하고, 급하면 /model로 다른 모델로 바꿉니다. 용량은 모델별로 관리되므로 Opus가 붐빌 때 Sonnet은 응답할 수 있습니다. 대체 모델 체인이나 무인 작업용 재시도 설정은 Claude Code 529 과부하 오류: 기다릴지, 모델을 바꿀지에서, 장애가 끝난 뒤 작업을 중복 없이 이어 가는 방법은 Claude Code 500과 529: 장애 후 중복 작업 없이 안전하게 재개하기에서 다룹니다. 500 오류라면 Claude Code API Error 500 해결법: Internal Server Error를 무작정 다시 시도하지 말기를 보세요.

누구에게 문의하고 무엇을 보낼까

응답한 곳이 정해지면 문의할 곳도 정해집니다. 중계 서비스의 오류를 Anthropic에 보내면 답을 받기 어렵습니다. 2026년 5월 Claude Code GitHub에 올라온 503 No available accounts 이슈 3건은 모두 중복으로 자동 종료됐고 Anthropic의 답변은 없었습니다. new-api 저장소도 이슈 양식에서 서드파티가 운영하는 인스턴스의 문제는 그 운영자에게 문의하라고 밝히고 있습니다.

어디에 문의하든 다음을 함께 보내면 한 번에 조사가 됩니다.

1. 오류 원문 전체. 중계 서비스가 붙여 준 request id가 있으면 반드시 포함합니다.
2. /status Status 탭의 Anthropic base URL, Auth token/API key/Login method 줄. 토큰 값은 가립니다.
3. claude --version 결과와 운영체제, 실행 환경(터미널 CLI인지 VS Code 확장인지).
4. 오류가 난 시각(시간대 포함)과 사용한 모델 이름.
5. 게이트웨이라면 위 1토큰 curl 테스트의 HTTP 코드와 응답 본문.

/feedback은 대화 기록과 설명을 Anthropic에 보내고, 미리 채운 GitHub 이슈를 여는 선택지도 줍니다. Anthropic 인증이 필요하며, Bedrock·Google Cloud·Microsoft Foundry 같은 서드파티 제공자를 쓰거나 Anthropic 자격 증명이 없으면 로컬 압축 파일만 저장되므로 그 파일을 Anthropic 계정 담당자에게 전달합니다. 설치 상태 자체가 의심스러우면 셸에서 claude doctor로 읽기 전용 진단을 돌려 볼 수 있습니다.

자주 묻는 질문

403이 뜨면 계정이 정지된 건가요?

대부분은 아닙니다. 로그인 직후의 Request not allowed는 구독이 비활성이거나 Console 역할이 없을 때 나고, 회사 프록시나 WAF, 중계 서비스, 심지어 Claude가 읽으려던 웹사이트도 403을 돌려줍니다. 오류 원문과 /status의 base URL 줄로 누가 거절했는지부터 확인하세요.

503이 뜨면 Anthropic 장애인가요?

base URL 줄이 있다면 먼저 게이트웨이나 중계 서비스를 의심하는 편이 맞습니다. Anthropic Messages API는 과부하를 529로 표시하고, 공식 오류 목록에 503은 없습니다. base URL 줄이 없고 status.claude.com에 장애 공지가 올라와 있을 때만 Anthropic 쪽 문제로 보고 기다리면 됩니다.

Claude Code를 재설치하거나 다시 로그인하면 해결되나요?

계정 역할, 프록시, WAF, 중계 서비스의 계정·채널 부족, Anthropic 용량 문제는 재설치나 재로그인으로 바뀌지 않습니다. 다시 로그인이 의미 있는 경우는 구독이나 역할을 바꾼 직후처럼 자격 증명을 새로 받아야 할 때이며, 그때도 /logout 후 /login이면 충분합니다.

529가 계속되면 계속 재시도해야 하나요?

Claude Code가 이미 최대 10회 재시도한 뒤라서 곧바로 다시 보내도 같은 결과가 나오기 쉽습니다. 몇 분 기다리거나 /model로 다른 모델로 바꾸는 편이 빠르며, 529는 할당량에서 차감되지 않으므로 한도를 걱정할 필요는 없습니다.