Claude API 연결 오류 해결: 네트워크, SDK 타임아웃, Claude Code, 게이트웨이 경로 점검

Claude API에서 연결 오류가 보이면 먼저 요청이 Anthropic까지 도달했는지 확인해야 합니다. HTTP status, JSON body, request-id가 모두 없다면 연결 계층 문제로 봅니다. 반대로 JSON의 종류, 메시지, request ID가 반환되었다면 순수한 연결 오류가 아니라 API response 분기로 이동해야 합니다.

처음에는 아래 표로 분기하세요.

상태 메모: 2026-04-29 19:04 Asia/Shanghai 기준 Claude API와 Claude Code는 operational이었습니다. 하지만 status page는 실시간 정보입니다. 독자는 지금 장애를 판단할 때 반드시 현재 Claude Status를 다시 확인해야 하며, 과거 green status만으로 로컬 문제라고 단정하면 안 됩니다.

중지 규칙: 실패한 path를 보존하고, retry 한 번에 변수 하나만 바꾸세요. escalation 전에 timestamp, region/network, route, SDK class, HTTP status, request ID, same-path retry 결과를 모읍니다.

request ID 경계부터 확인하기

한국어 사용자에게 "Claude API 연결 오류"는 단순한 에러 사전이 아닙니다. 지금 막힌 요청이 네트워크, VPN, firewall, proxy, SDK timeout, Claude Code route/auth, gateway, 아니면 이미 반환된 API response 중 어디에 속하는지 빠르게 알고 싶은 상황입니다. 처음 판단은 배경 설명보다 요청 도달 여부를 먼저 알려줘야 합니다.

Claude Help Center의 connection error 문서는 firewall, network restrictions, VPN을 우선 확인 대상으로 둡니다. 반면 Claude API Errors docs는 API가 반환한 오류를 error.type, error.message, request_id, request-id header로 다룹니다. 두 경계를 섞지 않는 것이 가장 빠른 복구 방법입니다.

응답이 없다면 DNS, TLS, proxy, VPN, firewall, corporate TLS inspection, container CA, CI runner, serverless region, SDK timeout에서 증거를 찾아야 합니다. request ID가 있다면 요청은 API layer에 닿았습니다. 이때는 status code와 error type을 분류해야지, 계속 VPN을 켜고 끄는 문제가 아닙니다.

이 경계는 현장 신호도 보존합니다. API key를 돌리고, provider를 바꾸고, plan을 업그레이드하고, Claude Code를 재설치하면 문제가 사라질 수도 있지만 무엇이 원인이었는지 알기 어려워집니다. 실패한 path를 남겨두고 하나씩 바꾸세요.

60초 same-path triage

처음 60초는 짧고 반복 가능해야 합니다.

1. Claude Status를 열고 Claude API, Claude Code, Console, claude.ai 중 어느 component인지 확인합니다.
2. 오류에 HTTP status, JSON body, request_id, request-id header가 있는지 봅니다.
3. 실제 요청 route를 정합니다. direct api.anthropic.com, SDK, Claude Code, corporate proxy, VPN, gateway, provider wrapper, CI, container 중 하나입니다.
4. 변수 하나만 바꾸고 같은 payload를 같은 route로 다시 실행합니다. 예: VPN off, proxy off, 다른 network, timeout 증가, Claude Code auth refresh.
5. 무엇을 바꿨고 무엇을 유지했으며 결과가 어떻게 달라졌는지 기록합니다.

same-path retry는 "몇 번 더 해보기"가 아닙니다. key, prompt, model, network, timeout, provider를 한 번에 바꾸고 성공하면 원인을 알 수 없습니다. VPN만 끄고 같은 request가 성공하면 network branch입니다. timeout만 늘리고 long request가 성공하면 timeout branch입니다. direct Anthropic은 성공하고 gateway만 실패하면 route branch입니다.

Anthropic의 connectivity check 안내도 valid API key로 test request를 보내고 status code, response body, error messages를 확인하는 흐름입니다. ticket이나 log에 API key, private prompt, customer data, proxy credential을 붙이지 마세요. 필요한 것은 route와 error evidence입니다.

Direct API: network, VPN, firewall, proxy, DNS, TLS

HTTP status도 body도 request ID도 없다면 direct API 도달성부터 봅니다. 문제의 owner는 local host, office firewall, VPN exit, corporate proxy, DNS, TLS certificate, Docker image, CI runner, serverless region, upstream route일 수 있습니다.

낮은 비용의 확인부터 시작하세요.

• VPN을 끄거나 trusted direct network로 바꿔 같은 request를 한 번만 재시도합니다.
• home network, mobile hotspot, office network, 다른 region의 cloud runner를 비교합니다.
• firewall, allowlist, proxy rule이 실제 endpoint를 허용하는지 봅니다.
• 실패하는 runtime에서 DNS와 TLS handshake를 확인합니다. 다른 컴퓨터의 browser 확인만으로는 부족합니다.
• corporate proxy가 TLS를 종료한다면 runtime trust store와 custom CA를 확인합니다.

"같은 환경"이 핵심입니다. browser가 help page를 열 수 있어도 backend worker, Docker container, WSL, VS Code Remote, GitHub Actions, serverless function은 다른 DNS, proxy, certificate store를 쓸 수 있습니다. 실제 API call을 보내는 process나 host에서 테스트해야 합니다.

다른 network path에서 같은 payload가 성공한다면 network branch 증거입니다. 바로 "Claude 장애"라고 쓰지 마세요. 여러 독립 network와 host가 동시에 실패하고 status나 public report도 같은 방향을 보일 때 platform-side 또는 regional route issue 가능성이 커집니다. 이 결론도 시간과 함께 기록해야 합니다.

SDK: APIConnectionError, timeout, returned API error

SDK exception은 응답을 받았는지 판단하는 단서입니다. Python SDK docs에서 APIConnectionError는 library가 API에 연결하지 못한 경우이고, APIStatusError는 non-2xx response가 반환된 경우입니다. TypeScript SDK docs에서 APIConnectionError는 HTTP status가 없는 connection branch이며, timeout은 APIConnectionTimeoutError로 볼 수 있습니다.

Python에서는 이렇게 분리합니다.

python
import os
import anthropic

client = anthropic.Anthropic(timeout=60.0, max_retries=2)

try:
    message = client.messages.create(
        model=os.environ["ANTHROPIC_MODEL"],
        max_tokens=256,
        messages=[{"role": "user", "content": "Say hello in one sentence."}],
    )
except anthropic.APIConnectionError as exc:
    print("connection branch", type(exc).__name__, str(exc))
except anthropic.APIStatusError as exc:
    print("returned API branch", exc.status_code, exc.response.headers.get("request-id"))

TypeScript에서도 같은 경계를 유지합니다.

ts
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({ timeout: 60_000, maxRetries: 2 });

try {
  const message = await client.messages.create({
    model: process.env.ANTHROPIC_MODEL!,
    max_tokens: 256,
    messages: [{ role: "user", content: "Say hello in one sentence." }],
  });
} catch (error) {
  if (error instanceof Anthropic.APIConnectionTimeoutError) {
    console.error("timeout branch", error.message);
  } else if (error instanceof Anthropic.APIConnectionError) {
    console.error("connection branch", error.message);
  } else if (error instanceof Anthropic.APIError) {
    console.error("returned API branch", error.status, error.headers?.["request-id"]);
  }
}

두 가지를 놓치기 쉽습니다. 첫째, SDK default retry가 첫 실패를 가릴 수 있습니다. 최종 실패 시간, retry count, SDK version을 기록하세요. 둘째, 긴 non-streaming request는 중간 network가 idle connection을 끊어 실패할 수 있습니다. prompt가 길거나 tool call이 느리거나 output이 크다면 streaming 또는 timeout을 먼저 확인하세요.

APIConnectionError는 rate limit이 아닙니다. HTTP status가 반환되면 해당 분기로 이동합니다. 529는 Claude API 529 overloaded error, 429는 Claude API rate-limit reached, Claude Code의 500은 Claude Code API Error 500을 확인하세요.

Claude Code: terminal route, auth state, environment

Claude Code에서 API Error: Connection error가 보이면 direct SDK와 같은 방식만으로는 부족합니다. Claude Code는 subscription OAuth, API key route, terminal proxy variables, WSL networking, VS Code Remote, corporate terminal proxy, provider wrapper를 사용할 수 있습니다.

먼저 확인할 항목입니다.

• /status를 실행해 active authentication method와 route를 기록합니다.
• Claude Code를 시작한 shell, IDE, WSL, container, CI에 ANTHROPIC_API_KEY가 있는지 확인합니다.
• HTTPS_PROXY, HTTP_PROXY, NO_PROXY, custom CA를 비교합니다.
• WSL 또는 VS Code Remote에서만 실패한다면 local terminal에서 같은 command를 실행합니다.
• route owner가 확인되기 전에는 reinstall이나 전체 cleanup을 하지 않습니다.

흔한 함정은 Claude Code가 항상 subscription login route를 쓴다고 믿는 것입니다. environment에 ANTHROPIC_API_KEY가 있으면 API-key route일 수 있습니다. browser의 Claude가 정상이어도 terminal proxy, DNS, certificate, key route는 별도 문제입니다.

route 설정 문제라면 Claude Code API configuration guide를 보세요. 반환된 오류가 Claude Code의 500/529/rate limit이라면 Claude Code 500/529/rate-limit router로 이동하세요.

Gateway/provider는 우회가 아니라 격리 테스트

gateway, proxy, OpenAI-compatible provider는 route owner를 확인하는 비교 도구가 될 수 있습니다. 하지만 첫 설명으로 쓰면 안 됩니다. direct Anthropic을 테스트할 수 있다면 baseline을 먼저 잡으세요. 그다음 같은 prompt, input size, model intent, timeout, environment를 유지하고 gateway route만 바꿉니다.

direct는 성공하고 gateway가 실패하면 gateway credential, model mapping, proxy, compatibility layer가 의심됩니다. direct는 실패하고 gateway가 성공하면 대체 route가 작동한다는 증거일 뿐, 공식 API 전체 장애의 증거는 아닙니다.

팀이 두 번째 API route로 격리하려는 경우 laozhang.ai를 gateway isolation route로 사용할 수 있습니다. 이 문맥은 route comparison에만 한정합니다. speed, uptime, quota, price, refund, guarantee는 fresh verification 없이는 주장하지 않습니다.

결과가 바뀌면 그 변수가 다음 owner입니다. 바뀌지 않으면 범위를 더 좁힙니다.

더 이상 connection error가 아닐 때

HTTP status, JSON body, request ID 중 하나라도 있으면 요청은 API layer에 닿았습니다. request ID를 보존하고 returned error로 분류하세요.

반환된 429나 529를 계속 connection error라고 부르면 복구가 틀어집니다. 429는 rate-limit handling, 529는 overload-aware retry, 500은 다른 escalation packet, DNS failure는 local network branch입니다.

escalation용 최소 evidence packet

status, request-id boundary, route owner, same-path retry를 확인했는데도 같은 path가 실패하면 escalation합니다. 필요한 것은 긴 설명이 아니라 분기가 보이는 증거입니다.

수집할 항목:

• timestamp와 timezone.
• SDK name, SDK version, runtime, host, region.
• exact error string과 exception class.
• 있으면 HTTP status, error.type, error.message, request ID.
• active route: direct Anthropic, Claude Code, gateway, proxy, VPN, CI, WSL, container, browser.
• 당시 Claude Status.
• 변수 하나를 바꾼 same-path retry result.
• secrets를 제거한 최소 reproduction.

API key, private prompt, customer data, credential이 있는 proxy log, 전체 request body를 보내지 마세요. 좋은 support packet은 길지 않고, 어떤 branch를 확인했고 같은 failure가 어떻게 남았는지를 명확히 보여줍니다.

자주 묻는 질문

Claude API 연결 오류는 보통 무엇을 뜻하나요?

status code, JSON body, request ID가 없다면 client가 API까지의 route를 완료하지 못했을 가능성이 큽니다. status, network, VPN, firewall, proxy, DNS/TLS, SDK timeout, route ownership을 확인하세요.

API key부터 바꿔야 하나요?

보통 아닙니다. no-response connection error에서는 key rotation보다 도달성과 route 확인이 먼저입니다. auth 또는 key owner 증거가 있을 때만 credential을 다룹니다.

Claude Status가 green이면 로컬 문제인가요?

단정할 수 없습니다. green status는 해당 component의 live incident 가능성을 낮출 뿐입니다. local network, SDK, Claude Code route, gateway, regional path는 별도로 고장날 수 있습니다.

SDK가 APIConnectionError를 내는데 HTTP status가 없는 이유는 무엇인가요?

SDK가 정상 API response를 받지 못했기 때문입니다. connectivity, proxy, DNS/TLS, VPN, firewall, timeout, route ownership을 봐야 합니다.

Claude Code의 API Error: Connection error도 같은 문제인가요?

request ID 경계는 같지만 Claude Code에서는 /status, ANTHROPIC_API_KEY, terminal proxy, WSL, VS Code, auth route도 확인해야 합니다.

gateway route는 언제 쓰나요?

direct access가 blocked이거나 compatible route를 비교해야 할 때 씁니다. prompt, input size, model intent, timeout은 고정하고 route만 바꾸세요.

support에는 무엇을 보내야 하나요?

timestamp, route, SDK/runtime, exact error, HTTP status, request ID, status page note, same-path retry result, redacted reproduction을 보내세요. 분기가 명확한 evidence가 더 유용합니다.

실무 규칙

Claude API 연결 오류는 response가 반환되기 전까지 reachability problem으로 다룹니다. 현재 status를 확인하고, request-id boundary를 유지하고, direct API, SDK, Claude Code, network/proxy, gateway branch를 선택한 뒤 변수 하나만 바꿔 같은 path를 재시도하세요. 그래도 실패하면 최소 evidence packet으로 escalation합니다.