429 Too Many Requests 체크리스트

Problem

요청에 대한 최종 응답 코드가 429 Too Many Requests로 반환됩니다.

Symptoms

• HTTP Check에서 최종 코드가 429입니다.
• 일정 시간 뒤 풀렸다가, 트래픽이 지속되면 다시 발생합니다.
• 일반 브라우징보다 API 클라이언트, 스크래퍼, CI 파이프라인, 공유 IP 뒤의 사용자에게 더 자주 걸립니다.

429가 실제로 뜻하는 것

RFC 6585(§4, 2012)은 429를 사용자가 “주어진 시간 동안 너무 많은 요청을 보낸 것(레이트 리밋)“으로 정의합니다. 핵심은 사용자(user) — 서버가 고장 난 게 아니라 누가 호출하느냐의 문제입니다. 명세는 “오리진이 사용자를 어떻게 식별하는지, 요청을 어떻게 세는지는 정의하지 않는다”고 분명히 밝힙니다. 서버는 리소스별·서버 전체·여러 대에 걸쳐 제한할 수 있고, IP·인증정보·쿠키를 키로 삼을 수 있습니다.

실무적 함의는 둘입니다. 첫째, 응답에 Retry-After 헤더가 실릴 수 있으니 재시도 전에 읽으세요. 둘째, 429 응답은 캐시에 저장하면 안 되므로(MUST NOT) 캐싱으로 덮어 가릴 수 없습니다.

Top 3 Causes

1. 애플리케이션·API 레이트 리밋 작동 - 오리진이 의도적으로 거는 키별·IP별·엔드포인트별 쿼터를 넘었습니다.
2. CDN·WAF의 엣지 차단 - Cloudflare “Error 1015”, WAF 규칙, 봇 보호가 요청이 오리진에 닿기 전에 막았습니다. 애플리케이션 버그가 아니라 엣지의 판단입니다.
3. 공유 IP가 한 클라이언트로 집계 - 사무실 NAT, VPN 출구, CI 러너가 여러 사용자를 하나의 주소 뒤에 묶어, IP별 한도가 예상보다 훨씬 빨리 걸립니다.

Diagnose with DechoNet

• HTTP Check로 최종 코드가 429인지 확인하고 Retry-After 헤더가 있는지 살핍니다.
• IP Check로 현재 내보내고 있는 주소를 확인합니다 — 공유·VPN IP가 레이트 리밋에 걸릴 때 유용합니다.

Resolution Checklist

• Retry-After 값을 읽고 그만큼 기다린 뒤 다음 요청을 보냅니다.
• 어느 계층이 응답했는지 식별합니다 — 오리진 애플리케이션 vs CDN/WAF(Cloudflare 1015는 엣지).
• 클라이언트에 백오프·재시도 로직을 넣어 한도를 밀어붙이지 말고 속도를 늦춥니다.
• 한도를 직접 운영한다면, 임계치와 식별자(IP vs 키)가 실제 사용 패턴에 맞는지 확인합니다.
• 여러 사용자가 하나의 외부 IP를 공유하는지 점검하고, API 키·토큰 단위로 제한합니다.
• 윈도우가 지난 뒤 HTTP Check를 다시 실행해 429가 사라졌는지 확인합니다.

When to Escalate

• 정상 워크로드가 바꿀 수 없는 임계치에 걸린다면 API·플랫폼 담당자에게 넘깁니다.
• 429가 CDN·WAF에서 온다면 엣지 관리자와 함께 레이트 리밋 규칙과 allowlist를 검토합니다.