API 429 오류, 다시 요청하기 전에 확인할 제한
API 요청 제한의 단위와 재시도·대기 처리 기준입니다.

오늘의 인사이트 요약
429 응답을 받으면 요청 제한의 대상과 시간을 먼저 확인합니다.
평균 호출 빈도와 순간 집중, 동시 실행 수는 구분해서 봅니다.
재시도에는 대기 시간과 종료 조건을 두고 작업 상태를 사용자에게 알립니다.
외부 서비스를 연결한 기능이 평소에는 잘 작동하다가 자료를 한꺼번에 처리할 때 멈추면 원인을 찾기 어렵습니다. 서버가 느린 것 같아 다시 실행했는데 오히려 오류가 늘어나기도 합니다. 이때 429 응답이 보인다면 API가 허용한 요청량을 넘겼는지 살펴봐야 합니다.
API 제공자가 정한 제한을 알면 연동 작업의 속도와 화면 안내를 함께 조정할 수 있습니다. 오늘은 API 요청 제한을 읽는 방법과 429 오류가 발생했을 때 확인할 재시도·대기 처리를 정리해보겠습니다.
429 응답은 어떤 제한을 뜻할까요?
429 Too Many Requests는 일정 시간 동안 클라이언트가 너무 많은 요청을 보냈다는 HTTP 상태 코드입니다. 같은 429라도 무엇을 기준으로 제한했는지는 제공 서비스의 정책과 응답을 확인해야 합니다. API 키, 사용자, IP 주소 등 집계 대상이 다를 수 있어 상태 코드 하나만으로 원인을 단정하기 어렵습니다.

가령 여러 직원이 쓰는 서비스가 하나의 연동 계정을 공유한다고 가정해 보겠습니다. 직원 한 명은 요청을 적게 보냈어도 합산 호출량이 제한에 걸릴 수 있습니다. 배치 작업과 사용자 화면이 같은 계정을 쓴다면 배치가 실행되는 동안 화면 요청까지 영향을 받는지도 확인합니다.
점검할 때는 실패 시각, 호출한 기능, 사용 계정과 응답 내용을 함께 남깁니다. 다만 인증키나 고객 자료 원문까지 로그에 넣을 필요는 없습니다. 요청 제한에 쓰일 수 있는 대상과 기본 응답 예시는 MDN의 429 설명에서 더 자세히 보실 수 있습니다.
평균 빈도와 순간 집중은 다른 조건입니다
“시간당 몇 회”라는 숫자만으로 모든 호출 조건을 설명할 수는 없습니다. 평균 요청 빈도와 짧은 시간에 몰리는 요청량을 별도로 제한하는 서비스가 있기 때문입니다. 한꺼번에 보내도 되는 양과 지속적으로 보낼 수 있는 속도를 나눠 읽어야 작업 시간을 예상하기 쉽습니다.

예를 들어 토큰 버킷은 일정 속도로 채워지는 토큰을 요청마다 사용하는 방식입니다. 남아 있는 토큰만큼 순간적인 요청을 받을 수 있지만 계속 몰리면 제한에 걸립니다. AWS API Gateway는 이 방식을 사용하며 설정한 제한을 절대 넘지 않는 상한으로 보장하지는 않습니다. 구현을 검토할 때는 API Gateway의 제한 설명을 참고해 보세요.
동시 실행 수도 요청 빈도와 구분합니다. 초당 호출이 적어도 응답이 오래 걸리면 진행 중인 요청이 쌓일 수 있습니다. 반대로 동시에 실행하는 작업을 줄여도 응답이 매우 빠르면 짧은 시간에 많은 호출이 나갑니다. 호출 간격과 진행 중인 작업 수를 함께 살펴야 어떤 제한에 걸리는지 알기 쉽습니다.
다시 보낼 때는 기다리는 방법도 필요합니다
429 응답에 Retry-After 헤더가 있다면 재요청 전 대기 시간을 해석합니다. 값은 초 단위 시간이나 HTTP 날짜 형식일 수 있습니다. 이 헤더가 항상 오는 것은 아니므로 없는 경우의 처리도 제공자의 문서에 맞춰 정합니다. 두 형식의 차이는 MDN의 Retry-After 안내에서 확인해 보세요.

즉시 재시도를 반복하면 제한에 걸린 서비스에 요청이 더 쌓일 수 있습니다. 실패가 이어질수록 대기 간격을 늘리고 요청들이 같은 순간에 재출발하지 않도록 대기 시간을 조금씩 흩어 주는 방법을 검토합니다. 이런 처리를 백오프와 지터라고 합니다. AWS의 재시도 설계 자료에서 요청 집중을 줄이는 원리를 더 자세히 보실 수 있습니다.
재시도에는 횟수나 전체 대기 시간 같은 종료 조건도 둡니다. 이미 SDK가 자동 재시도를 한다면 애플리케이션이 같은 동작을 중복으로 감싸고 있지 않은지 확인합니다. 결제나 등록처럼 상태를 바꾸는 요청은 API의 재시도 안전 조건과 기존 처리 결과도 확인해야 합니다. 모든 실패를 무제한 반복하면 작업 완료 시점과 실제 처리 여부를 파악하기 어렵습니다.
호출 속도와 사용자의 대기 경험을 함께 다룹니다
자료를 한꺼번에 옮기는 작업이라면 대기열에 넣고 허용 속도에 맞춰 처리하는 방법을 검토합니다. 처리량이 유입량보다 계속 적으면 대기열도 늘어나므로 단순히 줄을 세우는 것만으로 해결되지는 않습니다. 중복 호출을 줄이고, 제공 API가 지원한다면 묶음 요청을 쓰는 등 호출량 자체를 줄일 방법도 살펴봅니다.
사용자 화면에는 처리 중, 제한으로 대기 중, 실패처럼 실제 상태를 구분해 안내합니다. 시작 요청을 받았다는 이유로 전체 작업을 완료했다고 표시하면 사용자는 결과가 없는 상태에서 같은 작업을 다시 실행할 수 있습니다. 완료한 자료와 남은 자료를 나누고, 중단 후 어디서 재개할지도 정해 두면 운영 문의에 대응하기 쉽습니다.
출시 전에는 평소 요청뿐 아니라 여러 작업이 겹치는 상황, 429가 반복되는 상황, 대기 후 정상 처리되는 상황을 확인합니다. 전체 호출량과 제한 응답, 대기 시간, 최종 완료 여부를 연결해 보면 어디에서 처리가 밀리는지 찾기 쉽습니다. 제한값을 높일지 작업 방식을 바꿀지도 이 기록을 보고 판단합니다. API 요청 제한은 호출 코드와 운영 화면을 함께 설계할 때 다루기 쉬워집니다.
똑똑한개발자는 웹·앱과 관리자 시스템을 기획·디자인·개발·운영해 온 경험을 바탕으로 기존 시스템과 외부 서비스를 연결합니다. 연동 기능을 만들 때는 요청을 보내는 기능과 담당자가 처리 상태를 확인할 운영 흐름을 함께 살펴봅니다.

외부 API를 연결한 서비스의 대기 처리와 운영 흐름을 개선하고 싶다면 아래 똑똑한개발자 링크로 이야기 나눠주세요! 감사합니다.
AX 도입, 프로젝트 협업 등 궁금한 점을 남겨주세요.
https://www.toktokhan.dev/contact?utm_source=landing&utm_campaign=api-rate-limit-429&utm_medium=api-rate-limit-429&utm_term=API%EC%9A%94%EC%B2%AD%EC%A0%9C%ED%95%9C