속도 제한

속도 제한은 API 키 단위의 고정 60초 윈도우로 적용되며 경계에서 초기화됩니다. 기본값은 키당 분당 60회 요청이며 Production 워크로드에는 더 높은 한도를 협의할 수 있습니다.

응답 헤더

모든 응답에는 현재 속도 제한 상태가 포함됩니다.

헤더	의미
`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": "요청 한도를 초과했습니다.",
    "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을 추적하고 0에 도달하기 전에 속도를 낮추세요.
가능하면 배치 처리하세요. 다수의 POST /events 호출 대신 최대 500개 이벤트를 담는 POST /events/batch를 사용하세요(이벤트 API).
워크로드별로 키를 분리하세요. 한도는 키 단위이므로 대용량 수집과 인터랙티브 호출에 서로 다른 키를 사용하세요.
지원되는 멱등 작업은 안전하게 재시도할 수 있습니다. 이벤트는 event_id로 중복 제거하며 재생 토큰 생성, 라이선스 요청 생성, 키 회전은 X-NU-Request-Id를 허용합니다. 24시간 내 완료된 재요청은 원본 결과를 반환하고 처리 중인 중복은 409 conflict를 반환합니다.

Production 속도 제한 처리는 프로덕션 체크리스트의 일부입니다.