SaaS API 속도 제한: 사용자별·조직별·IP별 패턴

고객이 제한 때문에 혼란스러워하는 이유

레이트 리밋과 할당량(quota)은 비슷하게 들리지만 사람들은 종종 같은 것으로 취급합니다. 레이트 리밋은 API를 얼마나 빠르게 호출할 수 있는지(초당 또는 분당 요청 수)이고, 할당량은 더 긴 기간 동안 얼마나 사용할 수 있는지(일별, 월별 또는 청구 주기별)입니다. 둘 다 정상적인 제약이지만 규칙이 보이지 않으면 무작위처럼 느껴집니다.

고전적인 불만은 “어제는 됐어요”입니다. 사용량은 거의 고정적이지 않습니다. 짧은 스파이크로 인해 일일 총량은 괜찮아 보여도 임계치를 넘을 수 있습니다. 예를 들어 평상시 하루에 한 번 리포트를 돌리는 고객이 있는데, 오늘은 타임아웃 후 재시도하면서 2분 안에 10배의 호출을 발생시켰다고 상상해 보세요. API가 차단하고 고객이 보는 건 갑작스러운 실패뿐입니다.

오류 메시지가 애매하면 혼란은 더 커집니다. API가 500을 반환하거나 일반적인 메시지만 준다면 고객은 서비스가 중단됐다고 생각합니다. 그러면 긴급 티켓을 열거나 우회책을 만들거나 다른 공급자로 옮깁니다. 429 Too Many Requests도 다음에 뭘 해야 할지 알려주지 않으면 좌절을 불러옵니다.

대부분의 SaaS API는 트래픽을 제한하는 이유가 두 가지입니다:

• 남용 차단: 스크래핑, 무차별 대입, 또는 통제 불능 스크립트로부터 시스템을 보호합니다.
• 정상 사용형성: 특히 피크 시간대에 모두에게 안정적인 성능을 유지합니다.

이 목표를 섞으면 설계가 엉망이 됩니다. 남용 제어는 보통 IP나 토큰 단위로 엄격할 수 있습니다. 정상 사용형성은 사용자별이나 조직별로 하며 명확한 안내(어떤 제한에 걸렸는지, 언제 리셋되는지, 다시 걸리지 않으려면 어떻게 해야 하는지)가 필요합니다.

고객이 제한을 예측할 수 있을 때 계획을 세웁니다. 예측할 수 없으면 모든 스파이크가 고장난 API처럼 느껴집니다.

무엇을 보호할지 결정하기

레이트 리밋은 단순한 쓰로틀이 아닙니다. 안전 시스템입니다. 수치를 정하기 전에 무엇을 보호하려는지 명확히 하세요. 각 목표는 다른 한계와 기대를 만듭니다.

가용성(Availability)이 보통 먼저입니다. 몇몇 클라이언트가 트래픽을 폭증시켜 API가 타임아웃에 빠지면 모두가 고통받습니다. 이 경우 제한은 버스트 동안 서버가 응답하도록 유지하고 요청이 쌓이는 대신 빠르게 실패하게 해야 합니다.

비용은 많은 API 뒤에 숨어 있는 동인입니다. 일부 요청은 싸고, 일부는 비쌉니다(예: LLM 호출, 파일 처리, 스토리지 쓰기, 유료 서드파티 조회). 예를 들어 Koder.ai 같은 플랫폼에서는 한 사용자가 채팅 기반 앱 생성으로 많은 모델 호출을 트리거할 수 있습니다. 비용이 큰 작업을 추적하는 제한은 놀라운 청구서를 막아줍니다.

남용은 정상적인 높은 사용과 다르게 나타납니다. 자격 증명 채우기, 토큰 추측, 스크래핑은 좁은 범위의 IP나 계정에서 많은 작은 요청으로 보입니다. 이 경우 엄격한 제한과 빠른 차단이 필요합니다.

멀티테넌트 시스템에서는 공정성도 중요합니다. 하나의 시끄러운 고객이 다른 모든 사람의 성능을 떨어뜨려서는 안 됩니다. 실무에서는 일반적으로 여러 계층의 제어를 둡니다: 분당·분단위 건강을 지키는 버스트 가드, 비용이 큰 엔드포인트를 위한 비용 가드, 인증 및 의심스러운 패턴에 집중한 남용 가드, 그리고 한 조직이 다른 조직을 밀어내지 못하도록 하는 공정성 가드.

간단한 테스트가 도움이 됩니다: 하나의 엔드포인트를 골라 “이 요청이 10× 늘어나면 무엇이 먼저 망가지는가?”라고 물어보세요. 답이 어떤 보호 목표를 우선할지, 어떤 차원(user, org, IP)에 제한을 둘지 알려줍니다.

적절한 제한 차원 선택하기

대부분 팀은 하나의 제한으로 시작했다가 나중에 잘못된 사람들을 해치고 만다는 것을 발견합니다. 목표는 실제 사용 패턴에 맞는 차원을 선택하는 것입니다: 누가 호출하는가, 누가 비용을 지불하는가, 무엇이 남용처럼 보이는가.

SaaS에서 자주 쓰이는 차원은 다음과 같습니다:

• 사용자별(Per user): 한 사용자가 무거운 작업을 해도 동일 계정의 다른 사람들을 느리게 하지 않게 합니다.
• 조직/워크스페이스별(Per org/workspace): 테넌트의 총 사용량에 명확한 상한을 둡니다(대개 요금제가 판매하는 단위).
• IP별(Per IP): 봇, 자격 증명 채우기, 잘못 구성된 클라이언트가 한 주소에서 몰아칠 때 잡아냅니다.
• API 키/토큰별(Per API key/token): “사용자”가 의미가 없거나 공유되는 파트너·통합에 유용합니다.

사용자별 제한은 테넌트 내부의 공정성에 관한 것입니다. 한 사람이 대량 내보내기를 실행하면 팀의 다른 사람들보다 더 느끼는 것이 합리적입니다.

조직별 제한은 예산과 용량에 관한 것입니다. 열 명의 사용자가 동시에 작업을 실행하더라도 조직이 서비스나 가격 가정을 망가뜨릴 정도로 스파이크하면 안 됩니다.

IP별 제한은 청구 도구가 아니라 안전망으로 다루는 것이 좋습니다. IP는 공유될 수 있으므로(오피스 NAT, 모바일 통신사) 관대하게 두고 명백한 남용을 막는 데 주로 의존하세요.

차원을 조합할 때는 여러 제한이 적용될 경우 어느 것이 승리하는지 결정하세요. 실용적 규칙은: 관련된 어떤 제한이라도 초과하면 요청을 거부하고, 가장 행동하기 쉬운 이유를 반환하는 것입니다. 예를 들어 워크스페이스가 조직 할당량을 초과했으면 사용자나 IP를 탓하지 마세요.

예시: Koder.ai의 Pro 플랜 워크스페이스는 조직 단위로 일정한 빌드 요청 흐름을 허용하면서도 한 사용자가 분당 수백 요청을 보내는 것을 제한할 수 있습니다. 파트너 통합이 하나의 공유 토큰을 사용하는 경우 토큰별 제한으로 대화형 사용자를 압도하지 못하게 할 수 있습니다.

운영 환경에서 잘 쓰이는 알고리즘

대부분의 레이트 리밋 문제는 수학 문제가 아닙니다. 고객이 API를 호출하는 방식에 맞는 동작을 선택하고, 부하가 걸릴 때도 예측 가능하게 유지하는 문제가 핵심입니다.

토큰 버킷(Token Bucket)은 짧은 버스트를 허용하면서 장기 평균을 강제하므로 일반적인 기본값입니다. 대시보드를 새로고치면 짧은 시간에 여러 요청이 발생합니다. 토큰 버킷은 토큰을 모아두었다가 그 범위 내에서 허용하고 이후 속도를 줄입니다.

리키 버킷(Leaky Bucket)은 더 엄격합니다. 트래픽을 일정한 속도로 평탄화해서 백엔드가 스파이크를 못 견디는 경우(예: 비용이 큰 리포트 생성) 유용합니다. 단점은 고객이 더 빨리 제약을 느낄 수 있다는 점입니다.

윈도우 기반 카운터는 단순하지만 세부가 중요합니다. 고정 윈도우는 경계에서 급격한 변화를 만듭니다(예: 12:00:59와 12:01:00에 각각 폭주가 가능). 슬라이딩 윈도우는 더 공정하게 느껴지지만 더 많은 상태나 좋은 자료구조가 필요합니다.

별도의 제한 종류로 동시성(인플라이트 요청)이 있습니다. 느린 클라이언트 연결이나 시간이 오래 걸리는 엔드포인트로부터 보호합니다. 고객이 분당 60요청 이내여도 동시에 200개의 요청을 열어두면 시스템이 과부하될 수 있습니다.

실제 시스템에서는 일반적으로 소수의 제어를 결합합니다: 일반 요청률에는 토큰 버킷, 느리거나 무거운 엔드포인트에는 동시성 캡, 그리고 엔드포인트 그룹(저비용 조회 vs 비용이 큰 내보내기)에 대한 별도 예산을 둡니다. 요청 수만으로 제한하면 한 개의 비용 큰 엔드포인트가 전체를 잠가 API가 무작위로 고장난 것처럼 느껴지게 할 수 있습니다.

가격 및 사용량에 맞는 할당량 설계

좋은 할당량은 공정하고 예측 가능합니다. 고객이 차단된 뒤에야 규칙을 알게 되면 안 됩니다.

구분을 명확히 하세요:

• 단기 레이트 리밋(예: 초당 10요청)은 버스트로부터 서비스를 보호합니다.
• 장기 할당량(일간/월간)은 비용을 보호하고 요금제 간의 비교성을 유지합니다.

많은 SaaS 팀은 두 가지를 모두 씁니다: 버스트를 막는 단기 리밋과 요금제에 연동된 월간 할당량.

하드 리밋과 소프트 리밋은 주로 지원 정책 선택입니다. 하드 리밋은 즉시 차단합니다. 소프트 리밋은 먼저 경고하고 나중에 차단합니다. 소프트 리밋은 사람들에게 버그를 고치거나 업그레이드할 기회를 주어 화난 티켓을 줄입니다.

초과 시 동작은 보호하려는 대상에 맞춰야 합니다. 다른 테넌트에 피해가 가거나 비용이 폭주할 경우 차단이 적절합니다. 흐름을 계속 유지하고 싶다면 지연 처리나 우선순위 낮추기(Degrade)가 좋습니다. 사용량이 예측 가능하고 청구 흐름이 이미 있다면 “나중에 청구”도 가능할 수 있습니다.

티어 기반 제한은 각 티어가 “예상 사용 형태”를 명확히 가질 때 가장 잘 작동합니다. 무료 티어는 작은 월별 할당량과 낮은 버스트 한계를, 비즈니스·엔터프라이즈는 더 높은 할당량과 더 큰 버스트를 주어 백그라운드 작업이 빨리 끝나게 합니다. 이는 Koder.ai의 Free, Pro, Business, Enterprise 티어가 서로 다른 기대치를 설정하는 방식과 유사합니다.

엔터프라이즈용 커스텀 제한은 초기에 지원할 가치가 있습니다. 깔끔한 접근법은 “플랜별 기본값, 고객별 오버라이드”입니다. 조직별(때로는 엔드포인트별)로 관리자 설정 오버라이드를 저장하고 플랜 변경 후에도 유지되게 하세요. 또한 누가 변경을 요청할 수 있고 얼마나 빨리 적용되는지 결정하세요.

예: 고객이 월말에 50,000개의 레코드를 가져옵니다. 월별 할당량이 거의 소진된 상태라면 80–90%에서 소프트 경고를 보내 일시 중지할 시간을 주세요. 초당 제한은 가져오기 작업이 API를 범람시키지 않게 합니다. 승인된 조직 오버라이드(일시적 또는 영구적)가 있으면 비즈니스가 계속 진행됩니다.

단계별: SaaS API에 제한 구현하기

무엇을 카운트하고 누구에게 속하는지 먼저 적으세요. 대부분 팀은 세 가지 정체성을 갖습니다: 로그인한 사용자, 고객 조직(또는 워크스페이스), 그리고 클라이언트 IP.

실용적인 계획:

• 정체성 규칙 정의: auth에서 사용자 ID, 토큰 또는 API 키에서 org ID, 신뢰할 수 있는 첫 번째 프록시 홉에서 IP(어떤 헤더를 신뢰할지 명시).
• 엔드포인트를 비용별로 그룹화: 조회(read), 쓰기(write), 무거운 내보내기, 인증 흐름. 각 그룹에 다른 제한을 두어 한 비용 큰 엔드포인트가 전체 예산을 갉아먹지 않게 하세요.
• 카운터 위치 선택: 단일 인스턴스에는 인메모리, 여러 서버에 걸친 공유 제한에는 Redis, 느리고 감사용인 할당량에는 DB를 사용하세요. 윈도우에 맞는 TTL을 사용하세요(예: 분당 제한에는 60초).
• 일관된 강제 적용: IP 폭주에는 엣지(게이트웨이/CDN)에서 거칠게 차단하고, 라우트와 테넌트를 볼 수 있는 앱 미들웨어에서 세부적인 사용자/조직 체크를 하세요.
• 모든 것을 계측: 차단률(429), 제한기로 인한 지연, 차단되는 상위 키를 추적하세요. 차단이 급증하거나 Redis 오류로 인해 실패 오픈/클로즈 동작이 발생하면 알림을 받으세요.

제한을 설정할 때는 티어와 엔드포인트 그룹을 기준으로 생각하세요. 하나의 전역 숫자에 의존하는 것은 흔한 실패 원인입니다. 여러 애플리케이션 서버 간에 인메모리 카운터만 의존하면 카운터가 불일치해 사용자는 “무작위” 429를 경험합니다. Redis 같은 공유 저장소는 인스턴스 간 제한을 안정적으로 유지하고 TTL로 데이터를 작게 유지합니다.

롤아웃이 중요합니다. 먼저 “리포트 전용”(차단되었을 경우를 로깅)으로 시작하고, 그다음 하나의 엔드포인트 그룹을 강제 적용한 뒤 확장하세요. 이 방식이 지원 티켓 폭주를 피하는 방법입니다.

응답과 헤더로 제한을 이해시키기

고객이 제한에 걸렸을 때 최악의 결과는 혼란입니다: “API가 다운된 건가, 아니면 제가 뭔가 잘못했나?” 명확하고 일관된 응답은 지원 티켓을 줄이고 사용자가 클라이언트 동작을 고치게 합니다.

차단 중이면 HTTP 429 Too Many Requests를 사용하세요. 응답 본문을 예측 가능하게 만들어 SDK나 대시보드가 읽을 수 있게 하세요.

간단한 JSON 모양은 per-user, per-org, per-IP 제한 모두에 잘 작동합니다:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded for org. Try again later.",
    "limit_scope": "org",
    "reset_at": "2026-01-17T12:34:56Z",
    "request_id": "req_01H..."
  }
}

헤더는 현재 윈도우와 클라이언트가 무엇을 해야 하는지 설명해야 합니다. 최소한 다음을 포함하세요: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Retry-After, 그리고 X-Request-Id.

예: 고객의 크론 작업이 매분 실행되다가 갑자기 실패하기 시작했다고 가정합시다. 429과 함께 RateLimit-Remaining: 0 및 Retry-After: 20이 있다면 고객은 즉시 이것이 제한인지 아닌지 알 수 있고, 재시도를 20초 뒤로 미루게 할 수 있습니다. X-Request-Id를 지원에 공유하면 해당 이벤트를 빠르게 찾을 수 있습니다.

한 가지 더: 성공 응답에도 같은 헤더를 반환하세요. 고객이 차단되기 전에 경계에 가까운지 볼 수 있어야 합니다.

클라이언트 동작: 재시도, 백오프, 안전한 쓰기

좋은 클라이언트는 제한을 공정하게 느끼게 합니다. 나쁜 클라이언트는 일시적 제한을 장애로 만듭니다.

429을 받으면 속도를 줄이라는 신호로 받아들이세요. 응답이 언제 재시도할지 알려주면(예: Retry-After) 그 이상으로 기다리세요. 그렇지 않으면 지수 백오프와 지터를 사용해 수천 명의 클라이언트가 동시에 재시도하지 않게 하세요.

재시도는 범위를 제한하세요: 재시도 간 최대 지연(예: 30–60초)을 두고 총 재시도 시간(예: 2분)도 제한해 더 이상 재시도하지 말고 오류를 노출하세요. 또한 제한 세부 정보를 함께 로깅해 개발자가 나중에 튜닝할 수 있게 하세요.

모든 것을 재시도하지 마세요. 많은 오류는 변경이나 사용자 조치 없이는 성공하지 않습니다: 400 검증 오류, 401/403 인증 오류, 404 미발견, 409 충돌 등은 재시도해도 소용없습니다.

쓰기 엔드포인트(생성, 결제, 이메일 발송)는 재시도가 위험합니다. 타임아웃 후 클라이언트가 재시도하면 중복이 발생할 수 있습니다. 아이덴포턴시(idempotency) 키를 사용하세요: 클라이언트는 논리적 작업마다 고유 키를 보내고 서버는 동일 키가 반복되어도 같은 결과를 반환합니다.

좋은 SDK는 개발자에게 실제로 필요한 정보를 보여줄 수 있습니다: 상태(429), 얼마나 기다릴지, 요청이 안전하게 재시도 가능한지 여부, 그리고 “조직에 대한 레이트 리밋 초과. 8초 후 재시도하거나 동시성을 줄이세요.” 같은 메시지입니다.

화난 티켓을 만드는 흔한 실수들

대부분의 레이트 리밋 관련 지원 티켓은 제한 자체가 문제인 경우가 아닙니다. 문제는 놀람입니다. 사용자가 다음에 무슨 일이 일어날지 예측하지 못하면 API가 고장났거나 불공정하다고 가정합니다.

IP만 기반으로 제한을 두는 것은 흔한 실수입니다. 많은 팀이 하나의 공용 IP 뒤에 있습니다(사무실 Wi‑Fi, 모바일 통신사, 클라우드 NAT). IP로만 캡하면 한 바쁜 고객이 같은 네트워크의 모든 사람을 차단할 수 있습니다. 사용자별·조직별 제한을 선호하고, IP는 명백한 남용을 막는 안전망으로 사용하세요.

또 다른 문제는 모든 엔드포인트를 동일하게 취급하는 것입니다. 저비용 GET과 무거운 내보내기 작업이 동일한 예산을 공유하면 정상적인 탐색으로 할당을 소진하고 실제 작업을 시도할 때 차단될 수 있습니다. 엔드포인트 그룹별로 버킷을 분리하거나 요청에 비용 가중치를 두세요.

리셋 타이밍도 명확해야 합니다. “매일 리셋”만으로는 부족합니다. 어느 표준시인가요? 롤링 윈도우인가요, 자정 리셋인가요? 캘린더 리셋을 한다면 시간대를 명시하세요. 롤링 윈도우라면 윈도우 길이를 밝히세요.

마지막으로, 애매한 오류는 혼란을 만듭니다. 500이나 일반적인 JSON을 반환하면 사람들이 더 열심히 재시도합니다. 429와 RateLimit 헤더를 사용해 클라이언트가 지능적으로 백오프하도록 하세요.

예: 한 팀이 공유된 회사 네트워크에서 Koder.ai 통합을 구축하면 IP 전용 캡이 회사 전체를 차단하고 무작위 다운타임 같아 보일 수 있습니다. 명확한 차원과 429 응답은 이를 막아줍니다.

출시 전 빠른 체크리스트

모든 사용자에게 제한을 켜기 전에 예측 가능성에 초점을 맞춰 최종 점검을 하세요:

• 요금제와 엔드포인트 그룹별로 제한을 정의하세요(인증, 조회, 쓰기, 내보내기). 로그인이나 토큰 갱신 같은 필수 기능에는 작은 안전 버퍼를 두세요.
• 정체성 규칙을 결정하고 문서화하세요. 정확히 어떻게 카운트할지(user, org, API key, IP)와 우선순위를 정하세요.
• 429 응답을 자기 설명형으로 만드세요. Retry-After와 함께 RateLimit 헤더(Limit, Remaining, Reset)를 포함시키고, JSON 본문에는 어떤 제한이 걸렸는지와 재시도 시점을 짧게 적으세요.
• 스파이크와 오탐을 모두 모니터링하세요. 엔드포인트 그룹별 429 비율, 상위 호출자, 성공 요청의 갑작스런 감소를 추적하고 차단이 급증하면 알림을 설정하세요.
• 예외 처리 계획을 마련하세요: 화이트리스트, 일시적 증액, 긴급 오버라이드 및 승인 권한자.

직관적인 점검: 제품에 Free, Pro, Business, Enterprise 같은 티어가 있다면(예: Koder.ai) 정상 고객이 분당·일당 무엇을 할 수 있는지, 어떤 엔드포인트가 다르게 취급되는지 평이한 언어로 설명할 수 있어야 합니다.

429를 명확히 설명할 수 없다면 고객은 API가 보호하려는 것이 아니라 고장 났다고 가정할 것입니다.

예시 롤아웃 계획 및 다음 단계

워크스페이스(조직) 내부에서 사람들이 작업하는 B2B SaaS를 상상해 보세요. 몇몇 파워 유저가 무거운 내보내기를 돌리고 많은 직원이 하나의 공유 사무실 IP 뒤에 있습니다. IP로만 제한하면 전체 회사를 차단합니다. 사용자로만 제한하면 하나의 스크립트가 워크스페이스 전체를 해칠 수 있습니다.

실용적인 혼합은 다음과 같습니다:

• 단기적인 사용자별 버스트 제한.
• 시간이 지남에 따라 워크스페이스의 공정성을 지키는 조직별 지속 제한.
• 토큰 유출, 봇, 소음이 심한 공유 네트워크를 잡는 IP별 남용 가드.

누군가 제한에 걸리면 메시지는 무슨 일이 일어났는지, 다음에 무엇을 해야 하는지, 언제 재시도할 수 있는지를 알려야 합니다. 지원은 다음과 같은 문구를 뒷받침할 수 있어야 합니다:

“워크스페이스 ACME의 요청 속도가 초과되었습니다. 23초 후에 재시도하세요. 내보내기를 실행 중이라면 동시성을 2로 줄이거나 비피크 시간에 스케줄하세요. 정상 사용이 차단된다면 워크스페이스 ID와 타임스탬프를 회신하면 할당량을 검토하겠습니다.”

이 메시지를 Retry-After 및 일관된 RateLimit 헤더와 함께 제공하면 고객이 추측할 필요가 없습니다.

서프라이즈를 피하는 롤아웃: 먼저 관찰만(보고 전용), 그런 다음 경고(헤더와 소프트 경고), 그다음 강제 적용(재시도 시점이 명시된 429), 그리고 티어별 임계값 조정 및 주요 출시와 고객 온보딩 후 검토를 진행하세요.

이 아이디어들을 빠르게 작동하는 코드로 전환하고 싶다면, vibe-coding 플랫폼인 Koder.ai가 간단한 레이트 리밋 명세를 초안하고 여러 서비스에서 일관되게 적용할 Go 미들웨어를 생성하는 데 도움이 될 수 있습니다.