요청 한도와 할당량

한도는 플랜에 따라 다르며 API 키별로 계산돼요.

분당 요청 수#

키마다 최근 1분 동안의 요청을 세는 롤링 윈도우 방식이에요. 성공한 응답에는 모두 현재 윈도우에서 남은 요청 수를 알려 주는 X-RateLimit-Remaining 헤더가 포함돼요. 한도를 넘으면 429 rateLimited 오류가 반환되고, error.retryAfter 필드에 대기 시간이 초 단위로 담겨요.

X-RateLimit-Remaining: 59

{
  "error": {
    "code": "rateLimited",
    "message": "Rate limit exceeded",
    "retryAfter": 12
  }
}

월간 할당량#

키마다 월간 요청 할당량이 있으며, 매월 1일 00:00 UTC에 초기화돼요. 할당량을 모두 쓰면 다음 달까지 요청에 429 rateLimited 오류가 반환되고, error.reason 값은 quota로 설정돼요.

{
  "error": {
    "code": "rateLimited",
    "message": "Monthly quota exceeded",
    "reason": "quota"
  }
}

일일 스캔#

실제로 스캔을 시작한 POST /scans 호출은 플랜의 일일 스캔 한도에서 1회를 차감해요. 이 한도는 앱에서 시작하는 스캔과 공유돼요. 리포트 조회나, 유효한 캐시 리포트를 반환하는 스캔 호출은 스캔 한도를 차감하지 않아요(API 요청 수에는 포함돼요).

플랜별 한도#

권장 사항#

• 토큰 리포트는 직접 캐시하세요. 리포트는 몇 분 동안 최신 상태로 유지돼요.
• 429 응답을 받으면 retryAfter 초만큼 기다린 뒤, 지터를 더한 지수 백오프로 재시도하세요.
• 스캔은 쉬지 않고 반복 요청하지 말고 3~5초 간격으로 폴링하세요.
• 배치 작업은 한꺼번에 병렬로 보내지 말고 시간을 나눠 실행하세요.