HTTP 429 Too Many Requests

HTTP 429의 의미

HTTP 429 Too Many Requests는 클라이언트가 IP별, API 키별, 사용자별 또는 엔드포인트별 속도 제한을 초과했다는 의미입니다. 올바르게 동작하는 서버는 Retry-After 헤더(초 단위 또는 날짜)를 포함하며, 종종 할당량을 설명하는 X-RateLimit-* 헤더도 함께 제공합니다.

클라이언트 입장에서 올바른 대응은 항상 동일합니다. 속도를 늦추는 것입니다. 즉시 재시도하면 상황이 더 악화되며, 일시적인 제한이 실제 차단으로 확대될 수 있습니다.

429 오류의 일반적인 원인

• API 클라이언트가 너무 자주 폴링하거나 할당량을 초과해 요청을 몰아서 보냅니다.
• 요청 사이에 지연 없이 웹 스크래핑을 수행합니다.
• 버그: 백오프 없이 같은 엔드포인트를 계속 두드리는 재시도 루프입니다.
• 공유 IP(사무실 NAT, VPN, 서버리스 아웃바운드 트래픽 등)에서 합산된 트래픽이 제한을 초과합니다.
• 무차별 대입 공격 방지를 위해 로그인 엔드포인트가 반복된 시도를 제한합니다.

클라이언트/개발자 입장에서 해결하는 방법

• Retry-After를 정확히 따르세요. 값이 없다면 지터를 더한 지수 백오프(예: 1초, 2초, 4초, 8초…)를 사용하세요.
• API의 X-RateLimit-Remaining/초기화 헤더를 확인하고 미리 요청 속도를 조절하세요.
• 동일한 데이터를 반복해서 가져오는 대신 요청을 일괄 처리하고 응답을 캐시하세요.
• 일회용 IP를 여러 개 돌리는 대신 시간축으로 부하를 분산하세요. 제한을 회피하는 행위는 대개 API 이용 약관 위반입니다.

API 운영자 입장에서 해결하는 방법

• 클라이언트가 올바르게 대응할 수 있도록 항상 Retry-After와 할당량 헤더를 보내세요.
• 가능하다면 단순 IP보다는 키나 사용자 단위로 속도를 제한해 공유 네트워크가 불이익을 받지 않도록 하세요.

응답 예시

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0

{"error":"rate_limited","retry_after":30}

자주 묻는 질문