문서 검색...

문서를 검색하려면 입력을 시작하세요

플랫폼 가이드

오류 및 속도 제한

각 상태 코드의 의미와 그에 대한 대처 방법.

오류 형식

오류는 OpenAI 오류 형식의 JSON으로 반환됩니다. 메시지는 무슨 일이 있었는지 명시하고, code는 안정적인 기계 판독 식별자이며, 모든 메시지에 요청 id가 추가됩니다:

json
{
  "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"
  }
}

지원팀에 문의하거나 Discord 티켓을 열 때는 항상 요청 id를 포함하세요. 로그에서 정확한 요청을 찾을 수 있게 해줍니다.

상태 코드 한눈에 보기

실제로 마주치게 될 상태 코드:

코드의미대처 방법
400잘못된 요청: 잘못된 매개변수 값(예: 모델 최솟값보다 낮은 max_tokens) 또는 콘텐츠 검열에 의해 차단된 프롬프트.요청을 수정하세요. 변경 없이 재시도하면 다시 실패합니다.
401키 문제: API 키가 없거나 잘못되었거나 만료되었거나 비활성화되었습니다.Authorization 헤더와 토큰 페이지의 키를 확인하세요.
402이 키 자체의 지출 한도가 소진되었습니다.키의 한도를 높이거나 새 키를 만드세요.
403접근 거부: 계정 잔액이 비었거나, 이 키에 모델이 허용되지 않았거나, IP가 키의 허용 목록에 없습니다.충전하거나 키의 모델 및 IP 제한을 확인하세요.
413이 모델의 무료 체험 상한에 비해 요청이 너무 큽니다.프롬프트를 줄이거나 유료 모델로 전환하세요.
429속도 제한이 발동했습니다(아래 종류 참조).Retry-After 초만큼 기다린 다음 재시도하거나 모델을 전환하세요.
500당사 측 또는 업스트림 제공업체에서 무언가 실패했습니다.잠시 기다린 후 재시도하세요. 지속되는 500은 보고할 가치가 있습니다.
503모델의 모든 제공업체가 사용 중이거나 모델 이름이 존재하지 않습니다.메시지를 읽으세요: 사용 중은 몇 분 내에 해결되지만 오타는 그렇지 않습니다.

503: 사용 중 대 알 수 없는 모델

매우 다른 두 가지 상황이 503 상태를 공유합니다. 첫 번째는 일시적인 혼잡입니다:

text
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가 있는 503은 재시도/폴백으로, model_not_found가 있는 503은 클라이언트에서 하드 오류로 처리하세요.

속도 제한의 종류

429는 여러 계층에서 발생할 수 있습니다:

  • 당사의 무료 모델 상한: 사용자당 무료 모델당 분당 1회 요청. 공유 풀이 피크 시간대를 견디게 하는 공정성 상한입니다.
  • 업스트림 제공업체 제한: 무료 모델 뒤의 제공업체가 자체 상한에 도달했습니다("temporarily rate-limited upstream", 즉 업스트림에서 일시적으로 속도 제한됨).
  • 일부 무료 풀의 일일 토큰 예산. 이는 UTC 자정에 초기화됩니다.
  • 매우 큰 프롬프트에서 발동하는 분당 토큰 상한.
  • 너무 많은 요청이 병렬로 실행될 때의 사용자당 동시성 제한.

유료 모델에는 UnoRouter이 부과하는 속도 제한이 없습니다.

무료 모델 제한 상세

당사의 분당 1회 상한이 발동하면 표준 속도 제한 헤더를 받게 되어, 클라이언트가 정확하게 백오프할 수 있습니다:

text
HTTP/1.1 429 Too Many Requests
Retry-After: 38
X-RateLimit-Limit: 1
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1783198478

Retry-After는 동적입니다: 일률적인 60이 아니라 당신의 윈도에 실제로 남은 초입니다. 오류 메시지는 제한이 없는 그 모델의 유료 쌍둥이 이름도 알려줍니다.

체험 크기 상한

보통 유료인 일부 모델은 요청 크기 상한과 함께 무료로 제공됩니다. 너무 큰 프롬프트는 다음과 같은 메시지와 함께 413을 받습니다: Request body too large for gpt-4.1 model. Max size: 8000 tokens.

상한은 무료 체험 경로에만 적용됩니다. 유료 모델은 전체 길이의 프롬프트를 받습니다.

재시도 지침

429에서는 Retry-After를 준수하세요. 503 get_channel_failed는 잠시 기다린 후 재시도하거나 다른 모델로 폴백하세요. 400 계열 오류는 결정적이므로 재시도하지 마세요.

실패하거나 거부된 요청은 청구되지 않습니다: 잔액에 걸린 사전 보류는 요청이 오류로 끝나면 환불됩니다.

오류 코드 및 속도 제한