Erros - OrcaRouter

Envelope de erro

A maioria das respostas de erro usa este formato JSON compatível com OpenAI:

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

type é uma categoria ampla, code é um identificador específico. Algumas falhas de caminho rápido (notavelmente 429s no nível do workspace) retornam apenas um código de status HTTP com os cabeçalhos relevantes e nenhum corpo JSON.

Códigos de status HTTP

Status	Significado	Causa típica
`400`	Requisição inválida	Parâmetros inválidos, campos obrigatórios ausentes, violação de schema
`401`	Não autorizado	Chave de API ausente ou inválida
`403`	Proibido	Cota insuficiente, ou a chave não pode chamar este modelo
`404`	Não encontrado	Modelo ou endpoint não existe
`429`	Excesso de requisições	Limite de taxa atingido — veja Limites de taxa. A resposta sempre inclui um cabeçalho `Retry-After`.
`500`	Erro interno	Bug do lado do OrcaRouter
`502`	Erro upstream	Todos os provedores upstream falharam (incluindo qualquer cadeia de fallback)
`503`	Serviço indisponível	O modelo solicitado está temporariamente indisponível no upstream

Tipos de erro que você pode ver em `error.type`

`error.type`	De onde vem
`orcarouter_api_error`	Falhas do lado do gateway (auth, cota, rate-limit, interno)
`upstream_error`	O provedor upstream retornou um erro ou expirou
`openai_error`	Erro upstream compatível com OpenAI preservado literalmente
`claude_error`	Erro upstream da Anthropic preservado literalmente
`gemini_error`	Erro upstream do Gemini preservado literalmente

Códigos de erro que você pode ver em `error.code`

Estes são códigos emitidos pelo gateway para falhas que se originam no OrcaRouter (não no upstream):

`error.code`	HTTP	Significado
`insufficient_user_quota`	403	Crédito da conta esgotado. Faça recarga.
`model_not_found`	503	Este modelo não está disponível para sua conta.
`model_price_error`	400	Preço para este modelo não foi configurado. Contate o suporte.
`api_not_implemented`	400	Endpoint ou operação não suportado para o modelo escolhido.
`bad_request_body`	400	Corpo da requisição não pôde ser analisado.
`prompt_blocked`	400	Política de segurança do provedor bloqueou o prompt antes da geração.
`sensitive_words_detected`	400	Filtro de conteúdo sensível rejeitou o prompt.

Se você precisa distinguir programaticamente, faça match em error.code primeiro (específico) e caia para error.type (categoria ampla).

Erros de streaming

Erros durante uma resposta com streaming não podem usar códigos de status HTTP (o status foi enviado quando o stream foi aberto). O formato depende do endpoint:

`/v1/chat/completions` e `/v1/responses` (compatível com OpenAI)

O erro chega como um chunk in-band data: {...}:

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

data: [DONE]

Analise cada chunk data: como JSON; se ele tiver um campo error, trate o stream como falho.

`/v1/messages` (compatível com Anthropic)

A Anthropic usa eventos SSE nomeados. Uma falha de stream chega como:

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

O stream termina com event: message_stop (ou é cortado) depois do evento de erro.

Erros de fallback

Quando extra_body.models está definido e todos os modelos da cadeia falham, você recebe um 502 com detalhes sobre o último erro upstream. Os cabeçalhos de resposta X-Orca-Fallback-Level e X-Orca-Fallback-Model indicam qual fallback estava sendo tentado quando a cadeia esgotou. Veja Cabeçalhos de resposta.

​Envelope de erro

​Códigos de status HTTP

​Tipos de erro que você pode ver em error.type

​Códigos de erro que você pode ver em error.code

​Erros de streaming

​/v1/chat/completions e /v1/responses (compatível com OpenAI)

​/v1/messages (compatível com Anthropic)

​Erros de fallback