모든 사용자에게 안정적이고 신뢰할 수 있는 경험을 제공하기 위해, 업스테이지는 자원의 공정한 분배를 위해 API 요청에 사용량 한도(rate limit)를 적용해요. 이 가이드는 사용량 한도 정책을 설명하고, 한도 초과를 피하고 초과된 요청을 효과적으로 관리하는 데 도움이 되는 모범 사례를 안내해요.
사용량 한도란?
사용량 한도는 과도한 API 요청이 시스템 성능에 영향을 주지 않도록 하여 원활하고 안정적인 경험을 보장해요. 사용량 한도는 특정 시간 단위 안에서 허용되는 API 호출의 최대 횟수를 정의해요. 한도를 초과하면 추가 요청은 쿨다운 기간이 끝날 때까지 일시적으로 차단되며, 그 이후 다시 사용할 수 있어요. 업스테이지에는 다음과 같은 사용량 한도 정책이 적용돼요.
- RPS (Requests per second): 초당 허용되는 최대 API 요청 수
- RPM (Requests per minute): 분당 허용되는 최대 API 요청 수
- TPM (Tokens per minute): 분당 허용되는 최대 토큰 수 (Solar LLM과 같은 텍스트 기반 모델에 적용)
- PPM (Pages per minute): 분당 처리할 수 있는 최대 페이지 수 (문서 처리 모델에 적용)
사용량 한도를 초과하면 어떻게 되나요?
사용량 한도를 초과하면 서버는 HTTP 상태 코드 429 Too Many Requests로 응답해요.
이 경우, 지정된 쿨다운 기간이 끝난 후에 요청을 재시도해야 해요.
기능별 사용량 한도
다음 표는 약정 등급(Commitment tier)별로 정리된, 전체 기능에 대한 사용량 한도를 한눈에 보여줘요.
사용량 한도는 약정 등급(Commitment tier)에 따라 자동으로 배정돼요. 약정 등급과 가격에 대한 자세한 내용은 Pricing 페이지를 참고해주세요. 한도를 늘리려면 크레딧 페이지에서 크레딧을 구매해 약정 등급을 올려주세요. 어떤 약정 등급으로도 충족되지 않는 한도가 필요하다면 문의하기에서 요건을 알려 주세요.
Rate limit은 조직 단위로 정해지고, 조직의 모든 API 키가 같은 한도를 받아요. 요청 수는 키마다, 모델마다 따로 세기 때문에 한 키의 요청이 다른 키의 한도를 줄이지 않아요. 자세한 내용은 Rate limit은 API 키별로 적용되나요, 조직 단위로 적용되나요?를 참고해주세요.
Generate (Chat / Reasoning / Structured outputs)
Decide (구조화된 의사결정)
Solar Decide는 Solar Mini 4 위에서 제공되며, rate limit은 아래 기준이 별도로 적용돼요.
Embed
Parse (Document parsing / Document OCR)
Extract (Universal information extraction)
Classify (문서 분류)
Rate limit 응답 헤더
업스테이지 API는 모든 응답에 사용량 한도 상태를 알려주는 HTTP 응답 헤더를 포함해요. 이 헤더들을 사용하면 현재 사용량과 남은 허용량을 프로그램으로 모니터링할 수 있어, 사용량 한도 초과를 사전에 방지하는 데 도움이 돼요.
참고: 사용량 한도 값(Tier별 RPM/TPM/PPM 값)은 위의 기능별 사용량 한도 섹션을 참고해주세요.
헤더 카테고리
API 엔드포인트의 특성에 따라 응답에는 최대 세 가지 카테고리의 사용량 한도 헤더가 포함돼요.
| 카테고리 | 설명 | 대상 | 헤더 접미사 |
|---|---|---|---|
| RPS / RPM (Requests Per Second / Minute) | 초당 혹은 분당 요청 수 한도 | 모든 API 요청 | -Requests |
| TPM (Tokens Per Minute) | 분당 토큰 수 한도 | Chat, Embedding 등 토큰 기반 모델 | -Tokens |
| PPM (Pages Per Minute) | 분당 페이지 수 한도 | Document Parse, OCR 등 문서 처리 모델 | -Pages |
- RPS/RPM 헤더는 항상 포함돼요.
- TPM 헤더는 해당 모델에 TPM 한도가 설정된 경우에만 포함돼요.
- PPM 헤더는 해당 모델에 PPM 한도가 설정된 경우에만 포함돼요.
전체 헤더 목록
Limit (최대 허용량)
현재 사용량 한도 윈도우 내에서의 최대 허용량을 나타내요.
| 헤더 | 값 타입 | 설명 | 예시 |
|---|---|---|---|
X-Upstage-RateLimit-Limit-Requests | integer (string) | 초당 혹은 분당 최대 요청 수 | 500 |
X-Upstage-RateLimit-Limit-Tokens | integer (string) | 분당 최대 토큰 수 | 200000 |
X-Upstage-RateLimit-Limit-Pages | integer (string) | 분당 최대 페이지 수 | 500 |
Remaining (남은 허용량)
현재 사용량 한도 윈도우 내에서의 남은 허용량을 나타내요.
| 헤더 | 값 타입 | 설명 | 예시 |
|---|---|---|---|
X-Upstage-RateLimit-Remaining-Requests | integer (string) | 남은 요청 수 | 499 |
X-Upstage-RateLimit-Remaining-Tokens | integer (string) | 남은 토큰 수 | 195000 |
X-Upstage-RateLimit-Remaining-Pages | integer (string) | 남은 페이지 수 | 490 |
Reset (초기화 시각)
사용량 한도 윈도우가 초기화되는 시각을 Unix 타임스탬프(초 단위)로 나타내요.
| 헤더 | 값 타입 | 설명 | 예시 |
|---|---|---|---|
X-Upstage-RateLimit-Reset-Requests | Unix timestamp (string) | RPS/RPM 초기화 시각 | 1742300460 |
X-Upstage-RateLimit-Reset-Tokens | Unix timestamp (string) | TPM 초기화 시각 | 1742300460 |
X-Upstage-RateLimit-Reset-Pages | Unix timestamp (string) | PPM 초기화 시각 | 1742300460 |
Interval (윈도우 기간)
사용량 한도 윈도우의 기간 단위를 나타내요.
| 헤더 | 값 타입 | 가능한 값 | 설명 |
|---|---|---|---|
X-Upstage-RateLimit-Interval-Requests | string | "second", "minute" | RPS/RPM 윈도우 기간 |
X-Upstage-RateLimit-Interval-Tokens | string | "minute" | TPM 윈도우 기간 |
X-Upstage-RateLimit-Interval-Pages | string | "minute" | PPM 윈도우 기간 |
Retry-After (재시도 가능 시각)
사용량 한도를 초과한 경우(HTTP 상태 코드 429)에만 포함돼요. 요청을 재시도할 수 있는 시각을 Unix 타임스탬프(초 단위)로 나타내요.
| 헤더 | 값 타입 | 설명 | 예시 |
|---|---|---|---|
X-Upstage-RateLimit-Retry-After-Requests | Unix timestamp (string) | RPS/RPM 재시도 가능 시각 | 1742300445 |
X-Upstage-RateLimit-Retry-After-Tokens | Unix timestamp (string) | TPM 재시도 가능 시각 | 1742300445 |
X-Upstage-RateLimit-Retry-After-Pages | Unix timestamp (string) | PPM 재시도 가능 시각 | 1742300445 |
참고: Retry-After 헤더는 해당 카테고리의 사용량 한도를 초과한 경우(Retry-After > 0)에만 응답에 포함돼요. 성공 응답(HTTP 200)에는 포함되지 않아요.
응답 예시
성공 응답 (Chat API — RPM + TPM 적용)
성공 응답 (Document Parse API — RPM + PPM 적용)
사용량 한도 초과 응답 (HTTP 429 — RPM 초과)
참고: RPM을 초과한 경우에도 TPM/PPM 헤더는 각 카테고리의 현재 상태를 그대로 반환해요. Retry-After 헤더는 초과된 카테고리(이 예시에서는 Requests)에 대해서만 포함돼요.
프로그래밍 예시
Python
cURL
FAQ
Q: 모든 API 응답에 15개의 헤더가 모두 포함되나요?
아니에요. 해당 모델에 설정된 사용량 한도에 따라 카테고리별로 필요한 헤더만 포함돼요.
- Chat, Embedding 모델: RPM + TPM 헤더 (최대 10개)
- Document Parse, OCR 모델: RPM + PPM 헤더 (최대 10개)
- RPM 헤더는 모든 API 요청에 항상 포함돼요.
Q: Reset과 Retry-After는 어떻게 다른가요?
- Reset: 사용량 한도 윈도우가 완전히 초기화되는 시각이에요. 이 시각이 지나면 허용량이 전부 복원돼요.
- Retry-After: 사용량 한도를 초과한 경우(429)에만 포함되며, 요청을 재시도할 수 있는 가장 빠른 시각을 나타내요. Reset 시각보다 이전이거나 같아요.
Q: Interval 값으로 minute 외에 다른 값도 올 수 있나요?
코드 상으로는 second와 minute 두 가지가 가능해요. 현재 대부분의 사용량 한도는 minute 단위로 설정되어 있지만, 향후 변경될 수 있어요.
Q: 헤더 값이 음수일 수도 있나요?
아니요. Remaining 값은 0 아래로 내려가지 않아요. 한도에 도달하면 0으로 표시되고, 재시도할 수 있는 시각은 X-Upstage-RateLimit-Retry-After-* 헤더로 확인할 수 있어요.
사용량 한도 대응 모범 사례
백오프와 함께 재시도 로직 구현
다음 요청을 보내기 전 일정 시간 API 호출을 멈추는 재시도 로직을 구현해 보세요. 이렇게 하면 요청 간 간격이 충분히 벌어져 사용량 한도에 반복적으로 도달하는 상황을 피할 수 있어요. 예를 들어, 한도가 분 단위라면 다음 요청 전에 지연을 두거나, 재시도마다 대기 시간이 점진적으로 늘어나는 지수 백오프(exponential backoff)를 사용할 수 있어요.
비동기 API 사용
비동기 API는 일반적으로 더 높은 사용량 한도를 지원하므로 대량의 요청을 효율적으로 처리할 수 있어요. 일부 모델에는 비동기 API가 제공되며, 예시로 Document Parse가 있어요. 이 방식은 API 호출을 시간에 걸쳐 분산시키므로 성능을 최적화하면서도 사용량 한도 초과의 위험을 줄여줘요.
배치 처리
자주 개별 요청을 보내는 대신 배치 처리를 활용하는 것을 고려해 보세요. 여러 요청을 하나의 배치로 묶으면 API 호출 횟수를 줄여 사용량 한도 내에서 작업을 유지할 수 있어요. 특히 단시간에 다수의 요청을 처리해야 하는 대규모 임베딩 작업에 유용해요.
캐싱 전략
같은 데이터를 반환하는 API 요청이 잦다면 캐싱 전략을 도입해 요청 수를 크게 줄일 수 있어요. 특히 임베딩과 같은 시나리오에서 유용해요.
자주 발생하는 요청의 결과를 저장해 두고, 동일한 요청에 대해서는 API를 다시 호출하지 않고 캐시에서 응답을 제공해 보세요. 이렇게 하면 API 부하가 줄고 허용된 한도 내에서 운영하는 데 도움이 돼요.
더 높은 사용량 한도가 필요하신가요?
사용량 한도는 약정 등급(Commitment tier)에 따라 제공돼요. 더 높은 Tier에서는 더 큰 사용량 한도와 추가 혜택을 받을 수 있어요.
지금 바로 더 높은 한도가 필요하다면 크레딧을 구매하여 Tier를 업그레이드할 수 있어요.
- 일회성 구매: Tier 활성화 시점부터 한 달 동안 혜택이 유지돼요.
- 월간/연간 자동 충전: 각 결제 주기마다 혜택이 갱신되어 Tier가 계속 유지돼요.
엔터프라이즈 맞춤 계약이 필요하다면 문의하기에서 요건을 알려 주시면 비즈니스 담당자가 연락드릴게요.