호출 한도와 할당량
두 종류의 한도가 모두를 위해 API를 빠르게 유지해요.
- 키의 호출 한도: 키가 초당 보낼 수 있는 요청 수와 짧은 급증을 위한 버스트.
- 조직의 할당량: 조직의 모든 키가 합쳐서 분당, 일별, 월별로 보낼 수 있는 요청 수.
둘 다 조직의 요금제에 따라 달라요. 모든 응답이 현재 상태를 알려 주므로, 올바르게 동작하는 클라이언트는 짐작할 필요가 없어요.
키의 호출 한도
키마다 일정한 속도와 버스트가 주어져요. 버스트만큼은 요청을 한꺼번에 보낼 수 있고, 그다음부터는 일정한 속도로 요청이 허용돼요.
| 등급 | 속도 | 버스트 |
|---|---|---|
basic | 초당 요청 5개 | 25 |
standard | 초당 요청 20개 | 100 |
high | 초당 요청 50개 | 250 |
등급은 조직의 요금제에 따라 정해져요. GET /v1/me는 호출한 키의 등급, 속도, 버스트
(rate_limit)를 보여 줘요. 요청을 처리하는 API 서버가 몇 대이든 한도는 키 전체에 적용돼요.
스트리밍 엔드포인트인 POST /v1/chat("stream": true 여부와 관계없이)과 GET /v1/jobs/stream은 키의 호출 한도
밖에 있어요. 키의 호출 한도를 소모하지 않으며, 이 요청의 RateLimit 헤더에는 "key" 항목이 없어요. 다만 조직의
할당량에는 요청이 시작될 때 한 번씩 계산돼요. 질문에는 아래에서 설명하는 별도의 한도가 있어요.
조직의 할당량
요금제는 조직의 요청 할당량을 분당, 일별, 월별로 정할 수 있어요. 시간 창은 UTC 기준의 달력 단위예요. 1분은 :00초에,
하루는 00:00 UTC에, 한 달은 1일 00:00 UTC에 시작해요. 어느 주소로 보냈든 조직의 키나 OAuth 토큰으로 보낸 모든 요청이
계산돼요. 스트리밍 요청은 얼마나 오래 이어지든 시작할 때 한 번만 계산돼요. 할당량을 다 쓴 뒤에는 다른 요청과
마찬가지로 429로 거부돼요. 429로 거부된 요청은 계산되지 않아요.
헤더
키로 보낸 요청의 모든 응답에는 그 요청에 적용되는 한도가 담겨요.
RateLimit-Policy: "key";q=100;w=5, "minute";q=1200;w=60, "day";q=200000;w=86400
RateLimit: "key";r=87;t=1, "minute";r=1150;t=23, "day";r=180311;t=40213
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1
RateLimit-Policy와 RateLimit 헤더는 IETF 초안 RateLimit header fields for HTTP를 따라요. 각 항목이 한도 하나예요.
| 항목 | 의미 |
|---|---|
"key" | 키의 호출 한도. q는 버스트, w는 다 쓴 버스트가 다시 채워지는 데 걸리는 초예요. |
"minute", "day", "month" | 요금제에 있는 경우 조직의 할당량. q는 할당량, w는 초 단위의 시간 창이에요. |
r(RateLimit 헤더에서) | 이 한도에서 남은 요청 수. |
t(RateLimit 헤더에서) | 이 한도가 복원되기까지 남은 초. |
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset 헤더는 RateLimit 헤더가 생기기 전에 작성된
클라이언트를 위해 이 한도 중 가장 엄격한 것을 더 간단한 형태로 알려 줘요. X-RateLimit-Reset은 초 단위예요.
한도에 도달했을 때
API는 초 단위의 Retry-After 헤더와 함께 429 Too Many Requests로 응답해요.
| 코드 | 의미 |
|---|---|
api.rate_limited | 키가 허용된 속도보다 빠르게 요청을 보냈어요. Retry-After는 보통 1~2초예요. |
api.quota_exceeded | 조직의 할당량을 다 썼어요. 어느 할당량인지, 언제 초기화되는지는 details에 나와 있어요. |
{
"detail": "the organization has used its API request quota for this period",
"error": {
"code": "api.quota_exceeded",
"message": "the organization has used its API request quota for this period",
"details": {"quota": "day", "limit": 200000, "reset_at": "2026-10-25T00:00:00Z", "retry_after": 40213},
"request_id": "01JB7…"
}
}
Retry-After만큼 기다린 뒤 요청을 반복하세요. POST와 PATCH는 같은 Idempotency-Key로
반복하세요. 오류의 재시도 헬퍼가 둘 다 처리해 줘요.
요금제의 다른 한도도 Retry-After와 함께 429로 응답해요. 예를 들어 하루 질문 수
(limits.questions)나 동시에 진행 중인 답변 수
(limits.concurrent_answers)가 있어요. 같은 방식으로 처리하세요.