Liner API
요청 제한
요청 제한은 Liner API를 모두에게 안정적이고 공정하게 유지하기 위한 장치입니다. API 종류에 따라 다를 수 있고, 서비스 운영 정책에 따라 변경될 수 있습니다.
API 요청 제한
아래 표는 API별 기본 요청 제한을 요약한 것입니다.
LLM API
Search API
Visualization API
Agent API
Credits
- "No QPS limit"이 무제한 사용을 의미하지는 않습니다. 플랫폼 안정성 확보, 어뷰징 방지, 예상치 못한 트래픽 급증 등의 상황에서는 throttling이 적용될 수 있습니다.
- 계정 티어와 계약 조건, 엔드포인트 설정에 따라 제한 값은 달라질 수 있습니다.
- 한도는 계정 단위이며 계정의 모든 API 키가 함께 사용합니다. Liner Model API에서
liner-mark요청과 다른 모델 요청은 따로 셉니다. Chat Completions, Responses, Messages는 각 한도를 함께 쓰고, Decisions와 Batches는 다른 모델 한도에 포함됩니다. GET /api/v1/credits/balance와GET /api/v1/credits/usage는 하나의 한도를 함께 사용합니다. 합쳐서 초당 10회입니다. 다른 API보다 한도가 높은 이유는 조회가 무과금이고 처리 비용이 훨씬 작기 때문입니다.
에러 응답과 재시도
모든 에러는 같은 모양으로 옵니다.
{
"error": {
"code": "DOWNSTREAM_ERROR",
"message": "Upstream service temporarily unavailable",
"retryable": false
}
}상태 코드보다 retryable을 보세요
같은 상태 코드가 서로 다른 상황을 뜻할 수 있습니다. 예를 들어 502는 업스트림의 일시적인 장애일 수도 있고, 요청 자체가 거절된 것일 수도 있습니다. 이때 상태 코드는 같지만 retryable 값이 다릅니다.
retryable | 해야 할 일 |
|---|---|
true | Retry-After만큼 기다린 뒤 jitter를 포함한 exponential backoff으로 재시도하세요. |
false | 재시도하지 마세요. 요청을 고치거나(4xx) 크레딧을 충전해야(402) 합니다. |
Retry-After
재시도가 의미 있는 응답에만 붙습니다. 값은 초 단위입니다.
상황 | 값 |
|---|---|
요청 한도 초과 (초당) | 1 |
요청 한도 초과 (분당) | 다음 분까지 남은 초 |
모델 제공업체의 요청 제한 | 1 |
업스트림 일시 장애 | 5 |
이 값은 최소 대기 시간입니다. 그 위에 jitter를 포함한 backoff을 얹으세요. 모든 클라이언트가 정확히 같은 시각에 재시도하면 회복 중인 서비스에 부하가 다시 몰립니다.
retryable: true인데 Retry-After가 없는 경우(예: 500)는 복구 시점을 예측할 수 없다는 뜻입니다. 클라이언트 자체 백오프를 사용하세요.
스트리밍 응답의 실패
SSE 엔드포인트는 첫 chunk가 전송된 뒤에 실패하면 HTTP 상태 코드를 바꿀 수 없습니다. 이미 200으로 시작한 스트림 안에 에러 chunk가 들어옵니다.
event: data
data: {"type":"data-error","id":"data-error-1","data":{"code":"DOWNSTREAM_ERROR","message":"...","retryable":false}}
data: [DONE]
- 200을 받았다고 성공이 아닙니다.
[DONE]앞에type이data-error인 chunk가 있는지 확인하세요. data안의 필드는 위 JSON 에러 바디와 같습니다. 에러 처리 코드를 한 벌만 두면 됩니다.- 이 경로에는
Retry-After헤더가 없습니다(헤더가 이미 전송된 뒤이기 때문). 클라이언트 자체 백오프를 사용하세요.
요청 제한 동작 방식
1초 단위 고정 윈도우로 요청 수를 셉니다. 매초 카운터가 0으로 초기화되며, 초 단위로 독립적으로 판정합니다.
Liner Model API는 1분 단위 고정 윈도우도 함께 셉니다. 분당 한도는 초당 한도와 별도로 적용되며, 카운터는 매분 시작 시 초기화됩니다.
제한에 도달하면
제한을 초과하면 다음과 같이 동작합니다.
- API가 HTTP 429 Too Many Requests를 반환합니다.
- 잠시 멈춘 후 재시도하세요. 보통 capacity는 빠르게 회복됩니다.
권장 사항
- 429 응답에는 jitter를 포함한 exponential backoff을 구현하세요.
- 지원되는 곳에서는 요청을 batch로 묶어 보내세요.
- 매 요청마다 길고 반복되는 컨텍스트를 보내지 말고, 라우팅이나 요약을 활용해 쿼리를 컴팩트하게 유지하세요.
더 높은 제한이 필요하신가요?
높은 QPS나 보장된 burst capacity가 필요하다면 다음 정보와 함께 문의해 주세요.
- 예상 QPS·RPM
- 사용할 엔드포인트
- 일반적인 요청·응답 크기
- 사용자 응답 지연 요구사항