Rate limits & Quota

분당 호출 제한(sliding window) 과 월 호출 쿼터(402). 플랜별 상이.

Last updated: 2026-04-23

Veacon 은 두 가지 독립된 제한 을 적용합니다.

제한	범위	초과 시	집행
Rate Limit	분당 호출 수	HTTP 429 + `Retry-After`	Upstash Redis sliding window (전역)
Monthly Quota	월 성공 호출 수	HTTP 402 `QUOTA_EXCEEDED`	DB 카운터 + lazy 월경계 리셋

플랜별 한도

플랜	월 호출 쿼터	분당 Rate Limit
Free (Syncle SSO)	(제한 없음)	10 / min
Starter (₩50만/월)	10,000	60 / min
Pro (₩200만/월)	100,000	300 / min
Enterprise (₩500만+/월)	무제한	1,000 / min
Government	협의	협의

어떻게 카운트되나

Monthly Quota

HTTP 200-299 응답만 카운트 (Stripe/AWS billing 방식)
4xx, 5xx 응답은 카운트 X — 잘못 호출해도 쿼터 소진 X
매 달 첫 호출 시 자동 리셋 (lazy, 별도 cron 불필요)

Rate Limit

모든 호출(성공/실패 무관) 카운트
Sliding 60초 window — "지난 60초 동안 몇 번" 기준
인스턴스별 아닌 전역 공유 카운터 (Upstash Redis, Tokyo 리전)
인증이 필요한 엔드포인트에만 적용. /api/health 는 제외

응답 헤더

성공/실패 응답 모두에 다음 헤더가 포함됩니다.

Quota 관련

헤더	예시	의미
`X-Quota-Limit`	`10000`	이 API Key 의 월 한도
`X-Quota-Used`	`4237`	이번 달 사용량
`X-Quota-Resets-At`	`2026-05-01T00:00:00.000Z`	다음 리셋 UTC 시각

Rate limit 관련

헤더	예시	의미
`X-RateLimit-Limit`	`60`	분당 한도
`X-RateLimit-Remaining`	`58`	현재 분에 남은 호출 수
`Retry-After` (429 응답)	`35`	재시도까지 대기 시간 (초)

402 QUOTA_EXCEEDED 응답

쿼터 소진 시:

json

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Monthly quota of 10000 reached. Upgrade at https://veacon.io/pricing",
    "current_usage": 10000,
    "resets_at": "2026-05-01T00:00:00.000Z"
  },
  "_meta": { "service": "veacon", "api_version": "v1" }
}

다음 중 하나로 복구:

resets_at 까지 대기 (자동 리셋)
Pricing 에서 플랜 업그레이드 — 업그레이드 즉시 반영

429 RATE_LIMITED 응답

json

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded",
    "retry_after_seconds": 35
  },
  "_meta": { "service": "veacon", "api_version": "v1" }
}

응답 헤더 Retry-After: 35 초 대기 후 재시도. 연속 429 면 exponential backoff (1s, 2s, 4s, ...).

Best Practices

캐시 — /markets/dimensions 같이 자주 안 바뀌는 응답은 6시간 이상 캐시
배치 보류 — 대량 조회는 분당 한도 내로 분산 (ex: 100개 조합 → 10/min 으로 10분 분산)
헤더 모니터링 — X-RateLimit-Remaining, X-Quota-Used 를 로깅해 사용 패턴 추적
멱등 재시도 — GET 은 안전하게 재시도 가능. 4xx 는 재시도 금지

확장 한도 협상

Enterprise 고객은 다음 항목을 협상 가능:

월 쿼터 완전 무제한
분당 Rate Limit 1,000 이상
Dedicated Redis 인스턴스 (격리)
IP 화이트리스트 (P5 이후)
99.9% 월간 가용성 약정 (계약서 기준) + 미달 시 credit (Terms 제10조)

문의: hello@veacon.io