백엔드 API 레이트 리미팅 설계: 키·구간·429 응답을 정하는 기준

“로그인 요청이 몰릴 때 일반 사용자까지 막히면 어떻게 해야 할까?”

“IP만으로 제한하면 같은 사무실 사용자까지 함께 제한되지 않을까?”

“429를 반환한 뒤 클라이언트는 언제, 어떻게 다시 요청해야 할까?”

레이트 리미팅은 모든 요청에 같은 횟수 제한을 거는 일이 아닙니다. 요청 주체를 식별하는 키, API별 제한 구간, 429 이후의 클라이언트 행동을 함께 정해야 정상 사용자를 과도하게 막지 않으면서 서비스 자원을 보호할 수 있습니다.

제한값부터 정하면 예외 정책이 늘어나기 쉽습니다. 먼저 누구의 어떤 요청을 어느 범위에서 제어할지를 정하고, 그 정책을 클라이언트 화면과 운영 관측까지 연결하는 순서가 필요합니다.

어떤 요청을 같은 사용자로 묶어야 할까?

제한 키는 인증 여부와 보호하려는 자원 범위에 맞춰 정해야 합니다. 인증된 API는 사용자 ID·API 키·테넌트를 검토하고, 익명 요청은 IP의 한계를 감안해 별도 정책으로 다루는 편이 낫습니다.

제한 키는 어느 요청들이 하나의 카운터를 공유하는지를 결정합니다. 로그인 전 요청과 로그인 후 요청을 같은 기준으로 묶으면 반복 인증 시도와 일반 서비스 이용을 구분하기 어렵습니다. IP는 여러 사용자가 공유할 수 있고, 반대로 여러 IP로 분산된 요청에는 단일 IP 제한만으로 대응하기 어렵습니다.

API 키는 클라이언트별 사용량 제한과 비용 관리에 활용할 수 있지만, 탈취될 수 있으므로 민감하거나 고가치 자원을 API 키 하나만으로 보호해서는 안 됩니다. 제한 키와 엔드포인트 정책은 보호하려는 자원과 위험에 따라 조합해야 합니다. 출처: REST Security OWASP Cheat Sheet Series

로그인 API에 IP 기준과 계정 기준을 함께 둘 수는 있습니다. 다만 정책이 겹칠수록 거부 원인을 해석하기 어려워집니다. 각 키가 줄이려는 위험, 적용 라우트, 예외 처리 기준을 정책 문서와 로그에 남겨야 합니다.

제한 키를 정하기 전에 무엇을 확인해야 할까?

다음 질문에 답한 뒤 제한값을 정하면 정책의 이유를 설명하기 쉬워집니다.

• 이 요청은 인증 전인가, 인증 후인가?
• 동일 IP를 여러 정상 사용자가 공유할 가능성이 있는가?
• 사용자 한 명보다 테넌트 전체 사용량이 더 큰 위험이 되는가?
• 요청 한 건이 만드는 데이터베이스 작업, 외부 호출, 비동기 작업은 어느 정도인가?
• 여러 서버 인스턴스가 같은 제한 상태를 판단해야 하는가?
• 제한에 걸렸을 때 사용자가 수행할 수 있는 다음 행동은 무엇인가?

제한 정책의 구간과 범위는 어떻게 나눠야 할까?

하나의 전역 제한값보다 전역 보호, 라우트별 보호, 주체별 사용량, 오래 걸리는 작업의 동시성을 분리해 보는 편이 정책을 조정하기 쉽습니다.

고정 윈도우, 슬라이딩 윈도우, 토큰 버킷 같은 구현 방식을 먼저 선택하기보다, 먼저 허용할 순간 요청의 범위와 제한 상태를 어느 서버 인스턴스에서 공유할지를 문서화하세요. 알고리즘의 선택은 그 정책을 구현하는 수단으로 검토할 수 있습니다.

로그인처럼 짧은 시간의 반복 요청 자체가 위험 신호가 되는 라우트와, 화면 탐색 중 연속 호출될 수 있는 조회 라우트는 같은 정책으로 다루기 어렵습니다. 구현의 복잡도뿐 아니라 운영자가 제한 사유를 설명하고 변경할 수 있는지도 선택 기준에 포함해야 합니다.

1. 전역 보호 정책: 서비스 전체에 과도한 요청이 들어올 때 영향을 낮추는 기준입니다.
2. 라우트별 정책: 로그인, 검색, 외부 연동, 파일 처리처럼 비용과 위험이 다른 API를 구분합니다.
3. 주체별 정책: 사용자·API 키·테넌트 단위의 사용량을 관리합니다.
4. 동시성 정책: 오래 걸리는 작업은 요청 횟수와 별개로 동시에 진행할 수 있는 작업 수를 정합니다.

레이트 리미팅은 타임아웃, 재시도, 큐잉을 대신하지 않습니다. 입구에서 요청량을 줄이는 정책과 이미 시작한 작업이 의존성을 오래 점유하지 않게 하는 정책은 나눠 설계해야 합니다.

429 응답은 클라이언트가 행동할 수 있게 설계해야 한다

일반적인 요청 제한에서는 429 응답에 재시도 정보를 포함해 클라이언트가 기다리거나 사용자를 안내하도록 설계할 수 있습니다. 다만 상태 변경 요청의 자동 재시도는 멱등성과 사용자 흐름을 확인한 뒤에만 적용해야 합니다.

HTTP 429 Too Many Requests는 클라이언트가 일정 시간 동안 너무 많은 요청을 보냈음을 나타냅니다. 표준은 응답에 상황을 설명하는 세부 정보를 포함하도록 권고하며, 서버는 Retry-After 헤더를 포함할 수 있습니다. 다만 제한 대상, 요청 계산 방식, 응답 본문의 구체적 형식은 표준이 정하지 않으므로 API 계약에서 별도로 합의해야 합니다. 출처: RFC 6585: Additional HTTP Status Codes

Retry-After는 다음 요청 전 대기 시간을 HTTP 날짜 또는 지연 시간(초)으로 표현할 수 있습니다. 출처: RFC 9110: HTTP Semantics

서버가 429만 반환하고 클라이언트 동작을 정하지 않으면 사용자가 버튼을 반복해서 누르거나 여러 클라이언트가 같은 시점에 재시도할 수 있습니다. 읽기 요청처럼 재시도해도 안전한 요청과 생성·상태 변경처럼 중복 실행을 먼저 막아야 하는 요청을 분리하세요. 후자의 경우에는 자동 재시도보다 대기 안내, 사용자 확인, 멱등성 설계를 우선 검토해야 합니다.

김알레오는 프론트엔드 개발자로서 웹 서비스의 화면과 사용자 흐름을 다루는 맥락에서, 오류 메시지와 재시도 동작도 API 계약의 일부로 봐야 한다는 관점을 제안합니다. 재시도가 가능한 요청이라면 대기 이유와 다음 행동을 화면에 보여 주고, 적절하지 않다면 같은 요청이 반복 전송되지 않도록 제어하는 방식입니다.

응답 계약에는 다음 항목을 합의해 두는 편이 좋습니다.

• 상태 코드: 제한 상황과 일반 오류의 구분
• 오류 본문: 사용자 안내 메시지와 클라이언트 분기용 오류 코드의 구분
• 재시도 정보: 대기 시간 또는 재시도 가능 시점의 전달 방식
• 요청 식별 정보: 제한 이벤트와 서버 로그를 연결할 추적 정보
• 문서화: 제한 키, 대상 라우트, 예외 정책, 변경 절차

제한값은 배포 후 어떤 신호로 조정해야 할까?

초기 제한값은 정답이 아니라 관측을 시작하기 위한 가설로 두어야 합니다. 거부된 요청 수뿐 아니라 라우트별 집중도, 제한 주체, 의존성의 오류·지연 신호를 함께 보고 조정하세요.

429 발생 건수만으로 값이 너무 낮거나 높다고 판단하기는 어렵습니다. 정상 사용자 흐름에서 제한이 발생하는지, 특정 라우트에 집중되는지, 같은 주체가 반복 요청하는지, 제한 뒤 데이터베이스나 외부 연동의 압박이 줄었는지를 함께 확인해야 합니다.

운영 대시보드나 로그에서는 다음 질문에 답할 수 있어야 합니다.

• 어떤 라우트에서 제한이 가장 많이 발생하는가?
• 제한된 주체는 익명 IP, 사용자, API 키, 테넌트 중 무엇인가?
• 429 직후 같은 요청이 짧은 간격으로 반복되는가?
• 제한 이벤트와 애플리케이션 오류·지연이 같은 시간대에 발생하는가?
• 정책 변경 뒤 정상 사용자의 실패 신호가 늘었는가?

변경 전후를 비교할 때는 관측 기간, 변경한 제한 키와 라우트, 예외 처리를 함께 기록하세요. 그래야 다음 조정이 추측이 아니라 비교 가능한 운영 판단이 됩니다.

결론

안정적인 레이트 리미팅은 낮은 제한값에서 나오지 않습니다. 정상 사용자를 구분하는 키, API별 위험에 맞는 정책 범위, 429 이후의 명확한 행동을 연결하는 것이 핵심입니다.

처음 적용할 때는 모든 API를 한꺼번에 바꾸기보다 비용이 크거나 반복 요청 위험이 분명한 라우트 하나부터 고르세요. 요청 주체와 의존성을 적고, 제한 키와 정책 범위를 정한 뒤, 429를 받은 클라이언트의 동작을 합의합니다. 제한 이벤트와 서비스 지표를 함께 관측하면 다음 정책을 조정할 근거가 생깁니다.

자주 묻는 질문

IP 기준 제한만으로 충분한가요?

대체로 충분하지 않습니다. IP는 익명 요청을 분류하는 신호가 될 수 있지만 여러 정상 사용자가 공유할 수 있습니다. 인증된 API에서는 사용자 ID·API 키·테넌트 같은 식별자와 조합할지를 검토해야 합니다.

모든 API에 같은 제한값을 적용해도 되나요?

권장하기 어렵습니다. 로그인, 일반 조회, 외부 연동, 무거운 쓰기 요청은 위험과 후속 비용이 다르므로 라우트별로 정책을 나누는 편이 낫습니다.

429를 받으면 클라이언트가 자동 재시도해야 하나요?

항상 자동 재시도하면 안 됩니다. 재시도해도 안전한 읽기 요청과 중복 실행 위험이 있는 상태 변경 요청을 구분하고, 필요하면 사용자에게 대기 상태를 안내해야 합니다.

레이트 리미팅만으로 모든 악성 요청을 막을 수 있나요?

아닙니다. 레이트 리미팅은 애플리케이션 입구의 요청량을 제어하는 수단입니다. 인증·인가, 인프라 보호, 관측과 대응 절차는 별도로 갖춰야 합니다.

제 도움이 필요하시다면

API 제한 정책을 사용자가 이해할 수 있는 화면의 오류 안내와 재시도 흐름으로 연결해야 한다면, 요청 실패 상태를 인터페이스에서 어떻게 표현할지 함께 검토할 수 있습니다. 알레오는 웹 서비스 구현과 콘텐츠 운영 흐름을 다루며, API 오류·대기·재시도 경험을 화면 흐름과 연결해 살펴보는 출발점이 될 수 있습니다.

관련 서비스 맥락은 알레오 공식 웹사이트에서 확인해 보세요.