본문으로 건너뛰기

요청 한도

두 개의 버킷으로 요청 한도를 적용하며, 둘 다 충족해야 통과합니다.

토큰당 600 req/min
워크스페이스당 6000 req/min

응답 헤더

토큰 버킷 기준으로 다음 헤더가 반환됩니다.

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 547
X-RateLimit-Reset: 1717200000

한도는 60초 슬라이딩 윈도로 적용됩니다. X-RateLimit-Reset은 현재 윈도가 완전히 비워지는(추가 요청이 없을 때 한도가 회복되는) 가장 이른 Unix 초입니다. 특정 시점에 버킷이 한 번에 리셋되는 것이 아니라 윈도가 연속적으로 흘러가며 회복됩니다.

한도 초과

한도를 넘으면 429 RATE_LIMIT_EXCEEDED와 함께 Retry-After(초) 헤더가 반환됩니다. 응답 error.details.scope로 어느 버킷("token" 또는 "workspace")을 초과했는지 알 수 있습니다.

Retry-After만큼 대기하거나 jitter를 둔 exponential backoff를 권장합니다. 대량 조회 시에는 cursor 기반으로 나눠서 일정 간격을 두고 호출하세요.

참고

인증 실패(401)는 요청 한도를 소비하지 않습니다.
엔드포인트 미허용(403 PAT_INCOMPATIBLE_ENDPOINT)도 요청 한도를 소비하지 않습니다. 단, scope 부족(403 INSUFFICIENT_SCOPE)은 한도를 소비합니다.
Redis 장애 시 한도 적용이 일시적으로 비활성화(fail-open)되며, 이때 응답에 X-RateLimit-* 헤더가 생략될 수 있습니다.

응답 헤더
한도 초과
참고