요청 한도
요청 한도는 두 버킷으로 적용하며, 둘 다 충족해야 요청이 통과합니다.
- 토큰당 600 req/min
- 워크스페이스당 6000 req/min
같은 워크스페이스에서 토큰 여러 개를 쓰면 토큰별 한도와 별개로 워크스페이스 한도를 함께 씁니다.
응답 헤더
토큰 버킷을 기준으로 다음 헤더가 반환됩니다.
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 547
X-RateLimit-Reset: 1717200000
| 헤더 | 값 |
|---|---|
X-RateLimit-Limit | 토큰 버킷의 분당 한도 |
X-RateLimit-Remaining | 현재 60초 윈도에서 남은 요청 수 |
X-RateLimit-Reset | 추가 요청이 없을 때 현재 윈도가 완전히 비워지는 가장 이른 시각(Unix 초) |
한도는 60초 슬라이딩 윈도로 적용합니다. 특정 시점에 버킷이 한 번에 리셋되는 것이 아니라, 윈도가 연속으로 흘러가면서 오래된 요청부터 한도에서 빠집니다.
한도를 넘었을 때
한도를 넘기면 429 RATE_LIMIT_EXCEEDED와 함께 Retry-After(초) 헤더를 반환합니다. 응답의 error.details.scope는 어느 버킷을 넘겼는지("token" 또는 "workspace") 알려 줍니다.
Retry-After만큼 기다린 뒤 다시 보내거나, jitter를 둔 exponential backoff를 사용하세요. 많은 데이터를 읽을 때는 cursor로 나눠서 일정한 간격으로 호출하세요. 같은 워크스페이스의 다른 토큰이 한도를 쓰고 있다면 scope가 "workspace"로 오므로, 토큰을 더 만들어도 해결되지 않습니다.
엔드포인트별 워크스페이스 한도
아래 엔드포인트에는 위 한도와 별개로 워크스페이스당 한도가 따로 있습니다. 같은 워크스페이스의 토큰은 모두 이 한도를 함께 씁니다.
| 엔드포인트 | 워크스페이스당 한도 |
|---|---|
상담 유입(POST /conversations) | 분당 120회 |
게시판 답변 변경 조회(GET /board/answer-changes) | 분당 60회 |
이 한도를 넘겨도 429 RATE_LIMIT_EXCEEDED와 Retry-After를 반환하지만, 응답에 error.details.scope는 없습니다. 필요한 scope가 없어 403 INSUFFICIENT_SCOPE로 거절된 호출은 이 한도를 소비하지 않습니다. 그래서 같은 워크스페이스에 scope가 부족한 토큰이 있어도 다른 토큰이 쓸 한도는 줄지 않습니다. 자세한 내용은 상담 유입과 게시판 답변 변경을 참고하세요.
참고
- 인증 실패(
401)는 요청 한도를 소비하지 않습니다. - 엔드포인트 미허용(
403 PAT_INCOMPATIBLE_ENDPOINT)도 요청 한도를 소비하지 않습니다. scope 부족(403 INSUFFICIENT_SCOPE)은 위의 토큰·워크스페이스 공통 한도를 소비하지만, 엔드포인트별 워크스페이스 한도는 소비하지 않습니다. - 한도를 세는 서버(Redis)에 장애가 생기면 한도 적용이 일시적으로 꺼집니다(fail-open). 이때는 응답에서
X-RateLimit-*헤더가 빠질 수 있습니다.