429 Too Many Requests

사용법

429 Too Many Requests 상태 코드는 HTTP 요청 수가 허용된 임계값을 넘었음을 나타냅니다. 예를 들어 서버가 시간당 API 호출 수를 제한하려 할 때 발생합니다.

명세는 서버가 HTTP 요청을 어떻게 세는지, 사용자를 어떻게 식별하는지 정의하지 않습니다. 속도 제한은 리소스별, 사용자별, 서버 전체, 또는 여러 서버에 걸쳐 수행됩니다. 사용자 식별은 자격 증명을 사용하거나, 대안으로 쿠키를 사용해 이루어집니다.

서버는 요청이 다시 수락되는 시점을 클라이언트에 알리기 위해 선택적으로 Retry-After HTTP 헤더를 포함합니다.

참고

속도 제한은 일정 시간 창 안의 총 요청 수에 상한을 두는 것(엄격한 차단)이고, 스로틀링은 응답을 큐에 넣거나 지연시켜 요청 처리를 늦추는 것입니다. 대기 시간은 Retry-After 헤더에 따라 달라집니다. Retry-After가 없다면 흔한 시간 창은 API에 따라 60초에서 24시간 사이입니다. VPN 사용자는 다른 많은 사용자와 IP 주소를 공유하므로, IP별 속도 제한은 같은 서버의 모든 VPN 사용자에게 영향을 줍니다.

SEO 영향

Googlebot은 429를 서버 오류 신호로 취급합니다. 사이트가 429 응답을 반환하면 Google은 사이트 전체의 크롤링 속도를 일시적으로 줄입니다. 정상 응답이 재개되면 크롤링 속도는 점차 회복됩니다. 다른 4xx 코드와 달리 429 응답은 크롤 예산에 영향을 줍니다. 색인된 URL에서 429 응답이 지속되면 검색 결과에서 제거됩니다. Googlebot의 속도를 늦추려면 429가 올바른 상태 코드입니다. 401과 403은 크롤링 속도를 줄이지 않습니다. Bingbot도 429 응답을 받으면 크롤링 속도를 줄입니다. Bing은 추가로 상태 코드 기반 스로틀링의 대안으로 robots.txt의 crawl-delay를 지원합니다.

예시

클라이언트가 리소스를 요청하고 서버는 429 Too Many Requests로 응답합니다.

요청

GET /current-news HTTP/1.1
Host: example.com

응답

HTTP/1.1 429 Too Many Requests
Retry-After: 1800
Content-Type: text/html
Content-Length: 173

<html>
  <head>
    <title>Request Limit Exceeded</title>
  </head>
  <body>
   <p>The request limit has been reached.
   Try again in 30 minutes.</p>
  </body>
</html>

해결 방법

응답의 Retry-After 헤더를 확인하세요. 이 값은 서버가 요청을 다시 수락하는 시점을 초 단위 숫자 또는 HTTP 날짜로 지정합니다. 표시된 시점까지 모든 요청을 중단하세요.

재시도 사이에 지터를 섞은 지수 백오프를 구현하세요. 실패할 때마다 대기 시간을 두 배로 늘리고(1초, 2초, 4초, 8초) 무작위 오프셋을 더해, 여러 클라이언트가 같은 순간에 재시도하여 새로운 트래픽 급증을 만드는 일을 막으세요.

한도에 다다르기 전에 속도 제한 헤더를 모니터링하세요. 많은 API가 X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset 헤더를 포함합니다. 남은 횟수를 추적해 선제적으로 요청 속도를 낮추세요.

표준화된 속도 제한 필드

사실상의 표준인 X-RateLimit-* 헤더 외에, IETF는 할당량과 초기화 시점을 알리기 위한 RateLimit 및 RateLimit-Policy 응답 필드를 표준화하고 있습니다.

클라이언트 쪽에서 나가는 요청을 큐에 넣으세요. 전송 속도를 통제하는 요청 큐는 급증이 한도를 넘지 않도록 막아 줍니다. 엔드포인트가 일괄 작업을 지원한다면 여러 작업을 하나의 API 호출로 묶으세요.

요청 사이에 바뀌지 않을 데이터는 응답을 캐시하세요. 동일한 호출의 중복은 속도 제한을 불필요하게 소모하는 가장 흔한 원인입니다.

nginx의 서버 측에서는 limit_req_zone과 limit_req 지시문이 IP별 또는 엔드포인트별 속도 제한을 제어합니다. 속도 제한된 요청이 기본값인 503 대신 올바른 상태 코드를 반환하도록 limit_req_status 429;를 설정하세요. 짧은 트래픽 급증에 대해 즉시 거부하지 않으려면 burst와 nodelay 매개변수를 사용하세요.

AWS API Gateway에서는 스테이지나 메서드 수준에서 스로틀 설정을 구성하세요. 기본 임계값이 너무 제한적이라면 예상 트래픽 패턴에 맞게 rate와 burst 용량을 늘리세요.

코드 참고

.NET

HttpStatusCode.TooManyRequests

Rust

http::StatusCode::TOO_MANY_REQUESTS

Rails

:too_many_requests

http.StatusTooManyRequests

Symfony

Response::HTTP_TOO_MANY_REQUESTS

Python3.5+

http.HTTPStatus.TOO_MANY_REQUESTS

Apache HttpComponents Core

org.apache.hc.core5.http.HttpStatus.SC_TOO_MANY_REQUESTS

Angular

@angular/common/http/HttpStatusCode.TooManyRequests