오류 - OrcaRouter

오류 봉투

대부분의 오류 응답은 이 OpenAI 호환 JSON 형태를 사용합니다:

{
  "error": {
    "message": "Descriptive error message",
    "type": "orcarouter_api_error",
    "code": "model_not_found"
  }
}

type은 넓은 카테고리, code는 구체적 식별자입니다. 일부 빠른 경로 실패(특히 워크스페이스 레벨 429)는 JSON 본문 없이 HTTP 상태 코드와 관련 헤더만 반환합니다.

HTTP 상태 코드

상태	의미	일반적 원인
`400`	잘못된 요청	유효하지 않은 매개변수, 필수 필드 누락, 스키마 위반
`401`	미인증	API 키 누락 또는 유효하지 않음
`403`	금지	할당량 부족, 또는 키가 이 모델을 호출할 수 없음
`404`	찾을 수 없음	모델 또는 엔드포인트가 존재하지 않음
`429`	너무 많은 요청	속도 제한 적중 — 속도 제한 참조. 응답은 항상 `Retry-After` 헤더 포함.
`500`	내부 오류	OrcaRouter 측 버그
`502`	업스트림 오류	모든 업스트림 프로바이더가 실패(어떤 폴백 체인 포함)
`503`	서비스 사용 불가	요청된 모델이 업스트림에서 일시적으로 사용 불가

`error.type`에서 볼 수 있는 오류 타입

`error.type`	출처
`orcarouter_api_error`	게이트웨이 측 실패(인증, 할당량, 속도 제한, 내부)
`upstream_error`	업스트림 프로바이더가 오류 반환 또는 타임아웃
`openai_error`	OpenAI 호환 업스트림 오류 그대로 보존
`claude_error`	Anthropic 업스트림 오류 그대로 보존
`gemini_error`	Gemini 업스트림 오류 그대로 보존

`error.code`에서 볼 수 있는 오류 코드

OrcaRouter에서 발생하는 실패(업스트림이 아님)에 대한 게이트웨이 발행 코드:

`error.code`	HTTP	의미
`insufficient_user_quota`	403	계정 크레딧 소진. 충전하세요.
`model_not_found`	503	이 모델은 당신 계정에서 사용할 수 없습니다.
`model_price_error`	400	이 모델의 가격이 설정되지 않았습니다. 지원에 문의하세요.
`api_not_implemented`	400	선택한 모델에 대해 엔드포인트 또는 작업이 지원되지 않음.
`bad_request_body`	400	요청 본문을 파싱할 수 없음.
`prompt_blocked`	400	프로바이더 안전 정책이 생성 전에 프롬프트를 차단.
`sensitive_words_detected`	400	민감 컨텐츠 필터가 프롬프트를 거부.

프로그램적으로 구별해야 한다면 먼저 error.code(구체적)로 매치 하고 error.type(넓은 카테고리)으로 폴백하세요.

스트리밍 오류

스트림 응답 중 오류는 HTTP 상태 코드를 사용할 수 없습니다(상태는 스트림이 열릴 때 이미 전송됨). 형식은 엔드포인트에 따라 다릅니다:

`/v1/chat/completions`와 `/v1/responses` (OpenAI 호환)

오류는 인밴드 data: {...} 청크로 도착:

data: {"error":{"message":"...","type":"upstream_error","code":""}}

data: [DONE]

각 data: 청크를 JSON으로 파싱; error 필드가 있으면 스트림을 실패로 취급하세요.

`/v1/messages` (Anthropic 호환)

Anthropic은 SSE 명명 이벤트를 사용합니다. 스트림 실패는 다음과 같이 도착:

event: error
data: {"type":"error","error":{"type":"overloaded_error","message":"..."}}

오류 이벤트 후 스트림은 event: message_stop으로 종료(또는 절단) 됩니다.

폴백 오류

extra_body.models가 설정되고 체인의 모든 모델이 실패하면 마지막 업스트림 오류의 세부 정보가 포함된 502를 받습니다. 응답 헤더 X-Orca-Fallback-Level과 X-Orca-Fallback-Model은 체인이 소진 되었을 때 시도되던 폴백을 나타냅니다. 응답 헤더 참조.

​오류 봉투

​HTTP 상태 코드

​error.type에서 볼 수 있는 오류 타입

​error.code에서 볼 수 있는 오류 코드

​스트리밍 오류

​/v1/chat/completions와 /v1/responses (OpenAI 호환)

​/v1/messages (Anthropic 호환)

​폴백 오류