429 Too Many Requests

429 Too Many Requests는 일정 시간 동안 요청이 너무 많아 서버가 요청 속도를 제한하고 있음을 알리는 HTTP 상태 코드입니다. 서버가 응답에 재시도 대기 시간을 보낼 수 있으며, 제한 기준은 서비스마다 다릅니다. 같은 오류라도 IP 주소, 사용자 계정, 인증된 애플리케이션 중 무엇을 기준으로 세는지에 따라 여러 작업이 한도를 함께 사용할 수 있습니다.

요청 수와 시간 구간의 관계

RFC 6585의 429 정의는 일정 시간 안에 너무 많은 요청을 보낸 경우를 설명하며 이를 속도 제한이라고 부릅니다. 서비스는 요청을 처리할 수 있는 범위를 관리하기 위해 이런 응답을 보낼 수 있습니다. 429 자체에는 한 번에 허용하는 요청 수나 시간 구간의 길이가 들어 있지 않습니다. 같은 숫자를 받았더라도 실제 한도는 호출한 서비스의 문서와 응답 내용을 통해 확인합니다.

요청 제한은 개별 코드 한 줄보다 넓은 범위에 걸릴 수 있습니다. MDN의 429 설명은 서버 전체나 특정 자원에 제한이 적용될 수 있고, IP 주소 외에 사용자나 인증된 애플리케이션을 기준으로 할 수도 있다고 설명합니다. 한 계정으로 실행하는 여러 작업이 같은 한도를 쓰면 작업 하나의 요청 속도만 줄여도 전체 요청은 계속 많을 수 있습니다.

AI 에이전트가 도구를 반복 호출하거나 여러 배치 작업을 동시에 실행할 때도 이 구분이 필요합니다. 각 작업의 기록에 성공과 재시도를 따로 남기면 원래 요청량과 오류 뒤 추가 요청량을 나누어 볼 수 있습니다. 429가 왔다는 사실만으로 서버가 완전히 중단됐거나 계정이 영구 정지됐다고 판단하지 않습니다. 응답의 의미는 요청 속도 제한이며 구체적인 제한 단위와 해제 조건은 제공자의 정책에 달려 있습니다.

재시도 안내와 호출 계획

RFC 6585는 응답에 제한 상황을 설명하는 내용을 포함하도록 권고하고, 새 요청 전 대기 시간을 알리는 Retry-After 헤더를 넣을 수 있다고 정합니다. 이 헤더는 선택 사항입니다. 헤더가 없다고 즉시 재시도해도 된다는 뜻은 아니며, 헤더가 있다면 서비스가 보낸 값과 API의 재시도 규칙을 함께 해석합니다.

실패하자마자 같은 요청을 계속 보내면 제한 구간에 요청을 더 보태게 됩니다. 재시도 횟수와 대기 간격을 정하고 여러 작업의 재시도가 한 시점에 몰리는지도 확인하는 것이 운영상의 대응입니다. 이 대응은 HTTP 상태 코드 자체가 보장하는 자동 복구 기능이 아닙니다. SDK가 이미 재시도하고 있다면 애플리케이션의 반복문까지 겹쳐 전체 호출 수가 예상보다 늘어나는지도 살핍니다.

조회와 데이터 변경은 재시도의 영향도 다릅니다. 처리 결과를 확신할 수 없는 변경 요청을 반복하면 중복 작업이 생길 가능성을 따져야 합니다. 요청의 식별자와 제공자의 중복 방지 방식을 확인하면 같은 업무를 여러 번 실행하는 문제를 줄일 수 있습니다. 429의 정의만으로 모든 API의 부분 처리 여부나 과금 정책이 결정되지는 않으므로, 성공 여부와 청구 여부는 해당 API의 계약을 따로 읽습니다.

오류 기록과 정상 복구의 구분

MDN의 응답 예시는 반복 호출에 대해 429와 Retry-After를 돌려주는 상황을 보여 줍니다. 이 예시의 대기 시간은 설명용 값이며 모든 서비스가 쓰는 고정값이 아닙니다. 로그에는 상태 코드만 남기기보다 실제 응답의 제한 설명, 요청 시각, 대상 API를 함께 기록하면 제한 범위를 확인하기 쉽습니다.

작업이 나중에 성공했더라도 처음 받은 429를 성공 응답으로 바꾸어 기록하지 않습니다. 재시도 전 실패, 대기, 재시도 결과는 서로 다른 사건입니다. 배치 결과를 집계할 때도 성공 항목 수와 아직 제한으로 처리하지 못한 항목 수를 나누면 누락된 작업이 보입니다. 응답 본문이 오류 안내라면 필요한 데이터가 들어 있는 것처럼 다음 단계에 전달하지 않습니다.

복구 확인은 실제로 필요한 요청이 성공하고 기대한 결과를 얻었는지까지 이어집니다. 요청량을 줄였다는 설정 변경만으로 제한이 해제됐다고 보고할 수는 없습니다. 제한이 반복된다면 동시에 실행 중인 작업, 공유 계정, 호출 단위를 확인해 요청 계획을 조정합니다. 서비스가 제공하는 한도와 용도 안에서 처리량을 맞추고, 직접 측정한 요청 수와 추정한 원인을 구분해 기록합니다.