Saltar al contenido principal

​
Envoltura de error

La mayoría de las respuestas de error usan esta forma JSON compatible con OpenAI: 
{
  "error": {
    "message": "Descriptive error message",
    "type": "orcarouter_api_error",
    "code": "model_not_found"
  }
}
type es una categoría amplia, code es un identificador específico. Algunos fallos de camino rápido (notablemente los 429 a nivel de espacio de trabajo) devuelven solo un código de estado HTTP con las cabeceras relevantes y ningún cuerpo JSON.

​
Códigos de estado HTTP

EstadoSignificadoCausa típica
400Solicitud incorrectaParámetros inválidos, campos requeridos faltantes, violación de esquema
401No autorizadoClave API faltante o inválida
403ProhibidoCuota insuficiente, o la clave no puede llamar a este modelo
404No encontradoEl modelo o endpoint no existe
429Demasiadas solicitudesLímite de tasa alcanzado — ver Límites de tasa. La respuesta siempre incluye una cabecera Retry-After.
500Error internoBug del lado de OrcaRouter
502Error upstreamTodos los proveedores upstream fallaron (incluyendo cualquier cadena de respaldo)
503Servicio no disponibleEl modelo solicitado no está disponible temporalmente en upstream

​
Tipos de error que puedes ver en error.type

error.typeDe dónde viene
orcarouter_api_errorFallos del lado de la pasarela (auth, cuota, tasa, interno)
upstream_errorEl proveedor upstream devolvió un error o agotó el tiempo
openai_errorError upstream compatible con OpenAI preservado literalmente
claude_errorError upstream de Anthropic preservado literalmente
gemini_errorError upstream de Gemini preservado literalmente

​
Códigos de error que puedes ver en error.code

Estos son códigos emitidos por la pasarela para fallos que se originan en OrcaRouter (no en el upstream):
error.codeHTTPSignificado
insufficient_user_quota403Crédito de la cuenta agotado. Recarga.
model_not_found503Este modelo no está disponible para tu cuenta.
model_price_error400El precio para este modelo no está configurado. Contacta soporte.
api_not_implemented400Endpoint u operación no soportado para el modelo que elegiste.
bad_request_body400El cuerpo de la solicitud no se pudo analizar.
prompt_blocked400La política de seguridad del proveedor bloqueó el prompt antes de la generación.
sensitive_words_detected400El filtro de contenido sensible rechazó el prompt.
Si necesitas distinguir programáticamente, coincide primero en error.code (específico) y recurre a error.type (categoría amplia).

​
Errores de streaming

Los errores durante una respuesta en streaming no pueden usar códigos de estado HTTP (el estado se envió cuando se abrió el flujo). El formato depende del endpoint:

​
/v1/chat/completions y /v1/responses (compatibles con OpenAI)

El error llega como un fragmento data: {...} en banda: 
data: {"error":{"message":"...","type":"upstream_error","code":""}}

data: [DONE]
Analiza cada fragmento data: como JSON; si tiene un campo error, trata el flujo como fallido.

​
/v1/messages (compatible con Anthropic)

Anthropic usa eventos SSE con nombre. Un fallo de flujo llega como: 
event: error
data: {"type":"error","error":{"type":"overloaded_error","message":"..."}}
El flujo termina con event: message_stop (o se corta) después del evento de error.

​
Errores de respaldo

Cuando extra_body.models está configurado y todos los modelos en la cadena fallan, obtienes un 502 con detalles sobre el último error upstream. Las cabeceras de respuesta X-Orca-Fallback-Level y X-Orca-Fallback-Model indican qué respaldo se estaba intentando cuando la cadena se agotó. Ver Cabeceras de respuesta.