속도 제한
속도 제한은 API 키 단위로 고정 윈도우 카운터 (60초 윈도우이며, 카운터는 윈도우 경계에서 초기화됩니다)를 사용해 적용됩니다. 기본값은 키당 분당 60회 요청이며, 프로덕션 워크로드의 경우 더 높은 한도를 협의할 수 있습니다.
응답 헤더
모든 응답에는 현재 잔여 한도가 포함됩니다.
| 헤더 | 의미 |
|---|---|
X-RateLimit-Limit | 윈도우 내 허용 요청 수 |
X-RateLimit-Remaining | 현재 윈도우에서 남은 요청 수 |
X-RateLimit-Reset | 윈도우가 초기화되는 Unix epoch 초 |
한도를 초과하면 HTTP 429 응답과 함께 error.code = rate_limit_exceeded, 그리고 Retry-After 헤더(대기할 초)를 받습니다.
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1782604860
Retry-After: 12{ "error": { "code": "rate_limit_exceeded", "message": "rate limit exceeded", "request_id": "req_..." } }공개(미인증) 경로
공개 경로에는 API 키가 없으므로 클라이언트 IP 기준 분당 20회 요청으로 속도가 제한됩니다(동일한 고정 윈도우 카운터, 헤더, 그리고 429 + Retry-After 규약). 이는 POST /v1/partner-applications와 POST /v1/api-keys/bootstrap에 적용되어, 신청 스팸과 승인 토큰 무차별 대입을 억제합니다.
백오프 가이드
Retry-After를 준수하세요. 해당 초만큼 대기한 후 재시도하고, 엔드포인트를 무리하게 호출하지 마세요.- 반복되는 429 및
5xx에 대해서는 지터를 포함한 지수 백오프를 사용하세요. - 클라이언트 측에서 미리 스로틀링하세요.
X-RateLimit-Remaining을 추적하여 429에 반응하기보다 0에 도달하기 전에 속도를 늦추세요. - 가능하면 배치 처리하세요. 다수의 단건
POST /events호출 대신POST /events/batch(이벤트 500개 이하)를 사용하세요(이벤트 API). - 워크로드별로 키를 분산하세요. 한도가 키 단위이므로, 대용량 수집과 인터랙티브 호출을 서로 다른 키로 분리하세요.
- 이를 지원하는 멱등 작업에 대해서는 재시도가 안전합니다. 이벤트는
event_id로 중복을 제거하며, 재생 토큰 생성, 라이선스 요청 생성, API 키 회전은X-NU-Request-Id를 허용합니다(24시간 이내 완료된 재요청은 원본 결과를 반환하고, 처리 중인 중복 요청은409 conflict를 반환합니다).
프로덕션 속도 제한 처리는 프로덕션 체크리스트의 일부입니다.