공개 API
API 키마다 요금제별 한도가 있으며, 잘 동작하는 클라이언트에는 버스트를, 나머지에는 정확한 Retry-After를 제공합니다.
핵심 데이터API
속도 제한
원자적인 서버 측 속도 제한입니다. 명령 하나로 GCRA를 쓰거나, 슬라이딩 윈도우, 토큰 버킷, 리키 버킷을 쓰는 이름 있는 리미터를 사용합니다. Lua는 필요 없습니다.
- 요청당 원자적 명령
- 1
- 알고리즘
- 4
- Lua 스크립트
- 0
단계 1 / 5
허용
사용자 42에게 분당 10개의 요청입니다. 응답에는 허용 여부, 한도, 남은 횟수가 담깁니다.
예시 세션playing
# 허용
hotkv> GCRA.LIMIT ratelimit:user:42 60000 10
1) (integer) 0
2) (integer) 10
3) (integer) 9
4) (integer) -1
5) (integer) 6000
실제 HotKV 명령과 예시 응답으로 구성된 애니메이션 안내입니다. 원하는 단계를 클릭하면 해당 단계로 이동합니다. 명령과 응답은 HotKV에서 입력하고 보는 그대로 영어로 표시됩니다.
문제
제한이 없는 API는 잘못 동작하는 클라이언트 하나만 있어도 장애로 이어집니다. 애플리케이션 코드에서 검사하면 읽기, 계산, 쓰기가 필요하고, 동시 요청이 그 사이의 틈으로 빠져나갑니다. 많은 팀이 원자성을 위해서만 Lua 스크립트를 유지하게 됩니다.
HotKV의 해결 방식
GCRA.LIMIT는 판단과 기록을 한 단계로 처리하므로 동시 클라이언트가 같은 상태에서 함께 통과할 수 없고, 한도는 윈도우 경계에서 초기화되는 대신 부드럽게 다시 채워집니다. 이름으로 관리하는 한도에는 RATELIMIT.CREATE로 슬라이딩 윈도우, 토큰 버킷, 리키 버킷 리미터를 설정하며, 허용 및 거부 통계를 함께 제공합니다.
단계별 설명
명령 하나하나, 무슨 일이 일어나는가
- 01
허용
사용자 42에게 분당 10개의 요청입니다. 응답에는 허용 여부, 한도, 남은 횟수가 담깁니다.
GCRA.LIMIT ratelimit:user:42 60000 10 - 02
봇의 버스트
스크레이퍼는 버스트 허용량을 다 쓴 뒤 얼마나 기다려야 하는지 안내받습니다. 거부된 요청은 아무것도 바꾸지 않습니다.
GCRA.LIMIT ratelimit:bot:7 60000 10 - 03
요금제용 이름 있는 리미터
무료 요금제 고객은 슬라이딩 윈도우로 분당 100개의 요청을 받습니다.
RATELIMIT.CREATE free_plan 100 60000 ALGO sliding_window - 04
가중치가 있는 요청
내보내기 엔드포인트는 20단위가 들므로 허용량을 더 많이 사용합니다.
RATELIMIT.CHECK free_plan customer:881 COST 20 - 05
리미터가 한 일 확인
설정, 추적 중인 키, 허용 및 거부된 요청의 합계를 확인합니다.
RATELIMIT.STATS free_plan
적용 분야
실제 시나리오
로그인 및 가입 양식
IP별, 계정별 시도 횟수를 제한해 크리덴셜 스터핑을 늦춥니다.
외부 호출
파트너 API나 LLM 공급자에 대한 호출을 전체 워커에 걸쳐 할당량 이하로 유지합니다.
내장 기능
제공되는 기능
명령 하나로 GCRA
버스트를 허용하는 부드러운 재충전, 원자적 확인과 갱신, 거부 시 재시도 시간을 제공합니다.
GCRA.LIMITGCRA.RESET이름 있는 리미터
슬라이딩 윈도우, 토큰 버킷, 리키 버킷을 한 번 만들고 키별로 확인합니다.
RATELIMIT.CREATERATELIMIT.CHECK가중치가 있는 요청
비싼 호출은 여러 요청으로 셀 수 있습니다. GCRA.LIMIT는 개수를, RATELIMIT.CHECK는 COST를 받습니다.
COST통계
리미터별 허용 및 거부 합계를 제공합니다.
RATELIMIT.STATS자주 묻는 질문
속도 제한에 Lua 스크립트가 필요합니까?
아닙니다. GCRA.LIMIT와 RATELIMIT.CHECK 모두 전체 검사를 하나의 원자적 명령으로 처리합니다.
어느 것을 사용해야 합니까?
GCRA.LIMIT는 설정이 필요 없고 모든 플랜에서 동작합니다. RATELIMIT.* 이름 있는 리미터는 알고리즘 선택과 통계를 더하며, Performance 및 Scale 플랜에 포함됩니다.
거부된 요청에는 어떤 비용이 듭니까?
없습니다. 거부된 GCRA 호출은 리미터를 바꾸지 않으므로, 재시도하는 클라이언트가 추가로 불이익을 받지 않습니다.