속도 제한 및 오류
각종 제한과 상태 코드의 의미.
429는 여러 계층에서 발생할 수 있습니다:
- 저희 무료 모델 상한: 사용자별, 무료 모델별 분당 1회 요청.
- 상류 제한: 무료 모델 뒤의 제공자가 자체 상한에 걸렸습니다.
- 일부 무료 풀의 일일 토큰 예산. UTC 자정에 초기화됩니다.
- 분당 토큰 상한. 아주 큰 프롬프트에서 발생합니다.
- 동시 요청에 대한 사용자별 동시성 제한.
유료 모델에는 UnoRouter이 부과하는 속도 제한이 없습니다.
분당 1회 상한에 걸리면 표준 속도 제한 헤더가 옵니다:
HTTP/1.1 429 Too Many Requests
Retry-After: 38
X-RateLimit-Limit: 1
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1783198478Retry-After는 일률적인 60이 아니라 사용자 구간에 남은 초입니다. 메시지에는 제한이 없는 유료 모델 이름이 나옵니다.
일부 유료 모델은 요청 크기 상한을 두고 무료로 제공됩니다. 너무 큰 프롬프트는 413을 반환합니다: Request body too large for gpt-4.1 model. Max size: 8000 tokens.
이 상한은 무료 경로에만 적용됩니다. 유료 모델은 길이 제한 없이 프롬프트를 받습니다.
오류는 OpenAI 오류 형식의 JSON으로 반환됩니다. code는 변하지 않는 식별자입니다. 모든 메시지 끝에 요청 id가 붙습니다:
{
"error": {
"message": "Model \"gpt-5.5-typo\" is not offered here. Check the model name for typos, or switch to a model from our supported list. (request id: 20260705...)",
"type": "new_api_error",
"code": "model_not_found"
}
}지원 문의에는 요청 id를 함께 적어 주세요. 로그에서 해당 요청을 찾아냅니다.
키나 기본 URL을 아직 설정 중이라면 먼저 빠른 시작
실제로 마주치게 될 상태 코드:
| 코드 | 의미 | 대처 방법 |
|---|---|---|
400 | 잘못된 요청: 매개변수 오류이거나 모더레이션에 막힌 프롬프트. | 요청을 고치세요. 그대로 다시 보내면 또 실패합니다. |
401 | 키가 없거나, 잘못되었거나, 만료되었거나, 비활성화되었습니다. | Authorization 헤더와 Tokens 페이지를 확인하세요. |
402 | 이 키 자체의 지출 한도가 소진되었습니다. | 키의 한도를 높이거나 새 키를 만드세요. |
403 | 잔액이 없거나, 이 키로 그 모델이 허용되지 않거나, IP가 허용 목록에 없습니다. | 충전하거나 키의 모델 및 IP 제한을 확인하세요. |
413 | 요청이 해당 모델의 무료 체험 크기 상한을 넘었습니다. | 프롬프트를 줄이거나 유료 모델로 전환하세요. |
429 | 속도 제한이 발동했습니다(아래 종류 참조). | Retry-After 초만큼 기다린 다음 재시도하거나 모델을 전환하세요. |
500 | 당사 측 또는 업스트림 제공업체에서 무언가 실패했습니다. | 잠시 기다렸다 다시 시도하세요. 500이 계속되면 알려 주세요. |
503 | 모든 제공자가 붐비거나 모델 이름이 존재하지 않습니다. | 메시지를 읽으세요: 혼잡은 몇 분이면 풀리지만 오타는 풀리지 않습니다. |
매우 다른 두 가지 상황이 503 상태를 공유합니다. 첫 번째는 일시적인 혼잡입니다:
HTTP/1.1 503 Service Unavailable
{
"error": {
"message": "All providers for model \"kimi-k2.6:free\" are busy right now (they hit their rate limit). This is not a spelling error. Please try again in a little while, or switch to another model. (request id: 20260705...)",
"type": "new_api_error",
"code": "get_channel_failed"
}
}get_channel_failed는 그 모델의 모든 무료 제공자가 속도 제한에 걸렸다는 뜻입니다. 몇 분이면 풀리니 다시 시도하거나 모델을 바꾸세요. model_not_found는 이름이 해석되지 않는다는 뜻이라 다시 시도해도 소용없습니다. 오타나 카탈로그를 확인하세요.
get_channel_failed는 다시 시도할 수 있는 오류로, model_not_found는 확정적인 오류로 다루세요.
부하로 사라진 모델은 스스로 돌아옵니다. 돌아오는 순간 알림을 받으려면 여기서 관심 등록하세요: 알림
키가 제공자 그룹을 고정한 경우, 고정 그룹만 다운됐을 때의 세 번째 503이 있습니다. 다음을 참고하세요: 그룹 고정
429에서는 Retry-After를 지키세요. 503 get_channel_failed는 잠시 기다렸다 다시 시도하거나 모델을 바꾸세요. 400 계열 오류는 다시 시도하지 마세요.
실패하거나 거부된 요청은 절대 과금되지 않습니다. 선점과 환불의 동작은 다음에서 다룹니다: 계정 및 청구