Too Many Requests

개요

429 Too Many Requests는 클라이언트가 정해진 시간 안에 너무 많은 요청을 보내 속도 제한(rate limiting)에 걸렸다는 뜻입니다. API 남용·과도한 폴링·봇 트래픽으로부터 서버를 보호하기 위한 코드입니다.

잘 설계된 서버는 응답에 Retry-After 헤더(대기 시간, 초 또는 날짜)와 종종 RateLimit-* 헤더를 함께 실어, 클라이언트가 얼마나 기다렸다 재시도해야 하는지 알려줍니다.

언제 발생하나

• API의 초당/분당 요청 한도를 초과했을 때
• 재시도 로직에 백오프가 없어 요청이 폭주할 때
• 여러 인스턴스가 같은 API 키로 동시에 호출해 한도를 나눠 쓸 때

요청 / 응답 예시

GET /api/search?q=test HTTP/1.1
Host: api.example.com
Authorization: Bearer abc123

HTTP/1.1 429 Too Many Requests
Retry-After: 30
RateLimit-Remaining: 0
Content-Type: application/json

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

코드로 보기

async function fetchWithBackoff(url, tries = 5) {
  for (let i = 0; i < tries; i++) {
    const res = await fetch(url);
    if (res.status !== 429) return res;
    const wait = Number(res.headers.get('Retry-After') || 2 ** i);
    await new Promise(r => setTimeout(r, wait * 1000));
  }
  throw new Error('rate limited');
}

# Limit each client IP to 10 req/s, returning 429 on excess
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
location /api/ {
  limit_req zone=api burst=20 nodelay;
  limit_req_status 429;
}

실무 참고

• 429는 재시도가 유효한 일시적 오류입니다. 다만 무작정 즉시 재시도하면 상황이 악화되니 반드시 백오프를 넣으세요.
• Retry-After가 없으면 지수 백오프로 대기 시간을 스스로 늘려가며 재시도하는 것이 안전합니다.
• 여러 워커가 한 키를 공유하면 개별로는 적어 보여도 합산 한도를 넘길 수 있습니다 — 전역 레이트 리미터로 조율하세요.

관련 상태코드

관련 헤더

스펙 근거