문제가 생겼을 때
아무 추측 없이 엔지니어처럼 API 오류를 진단해요
⏱ 예상 ~6분
01 · 읽기
API 는 깨져요. Server 는 다운돼요. 키는 만료돼요. 요청 제한에 걸려요. URL 에 오타가 나요.
초보자와 엔지니어의 차이는 일이 잘못되는지 여부가 아니에요 — 얼마나 빨리 진단하고 고치는지예요.
체계적인 접근:
1. 상태 코드 읽기 — 어떤 오류 카테고리인가? 2. 응답 본문 읽기 — 서버가 보통 뭐가 잘못됐는지 명확히 말해줘요 3. 헤더 보기 — Retry-After, WWW-Authenticate, X-RateLimit-* 가 보물이에요 4. URL 확인 — 오타 하나로 모든 게 깨질 수 있어요
핵심 정리
- 디버그 시 항상 curl -i 사용 — 헤더를 봐야 해요
- 오류 본문은 상태 코드보다 보통 더 유용해요
- 4xx = 너의 문제. 5xx = 그쪽 문제.
- 아무것도 안 되면 API 제공자의 상태 페이지를 봐요
02 · 코드 예제
상태 코드 카테고리별 진단 체크리스트.
4xx — Client 오류 (너의 잘못)
400 Bad Request
→ Check: Is your JSON valid? Are required fields present?
→ Fix: Validate your -d body. Check the API docs for required fields.
401 Unauthorized
→ Check: Did you include the Authorization header? Is the key correct?
→ Fix: Check your API key. Make sure you're using the right header format.
403 Forbidden
→ Check: Do you have permission? Is this feature on your plan?
→ Fix: Check your account permissions or upgrade your plan.
404 Not Found
→ Check: Does the URL path exist? Did you replace all {placeholders}?
→ Fix: Double-check the URL against the docs. Check the resource ID.
429 Too Many Requests
→ Check: Look for Retry-After header — it tells you when to retry.
→ Fix: Slow down. Implement exponential backoff. Use caching.
5xx — Server 오류 (그쪽 문제)
500 Internal Server Error
→ Their code crashed. Check their status page.
→ Retry after a brief wait.
503 Service Unavailable
→ Server is overloaded or in maintenance.
→ Check their status page. Wait and retry.
504 Gateway Timeout
→ Your request took too long. The server gave up.
→ Try again. If persistent, contact the API provider.
curl 오류 (응답조차 못 받음)
curl: (6) Could not resolve host
→ DNS failure. Check the hostname for typos.
→ Verify your internet connection.
curl: (7) Failed to connect
→ Server unreachable or port blocked.
→ Check if the service is down.
curl: (35) SSL certificate problem
→ Certificate expired or invalid.
→ Check if you're using https:// correctly.
03 · 실기 실습
존재하지 않는 GitHub repo 에 요청을 보내서 진짜 404 를 일으켜요.
curl -i https://api.github.com/repos/this-user-doesnt-exist-xyz/no-such-repo
04 · 실기 실습
인증이 필요한 엔드포인트에 미인증 요청을 보내서 진짜 401 을 일으켜요.
curl -i https://api.github.com/user
05 · 퀴즈
API 를 호출했더니 429 상태 코드가 왔어요. 뭘 해야 하나요?
- API 키를 확인해요
- URL 을 바꿔요
- POST 요청으로 바꿔요
- 잠시 기다렸다가 재시도해요 — 요청 제한에 걸렸어요
06 · 빈칸 채우기
4 로 시작하는 상태 코드는 오류가 _____ 쪽에 있다는 뜻이에요 (요청이 잘못됨).
⚠ 전체 인터랙티브 경험에는 JavaScript가 필요해요. JavaScript를 켜고 새로 고침해 주세요.
※ 이 사이트는 독립 운영되는 교육 프로젝트로, Anthropic의 공식 제품이 아니에요. Claude™ 는 Anthropic, PBC 의 상표예요.