Vai al contenuto principale

​
Envelope di errore

La maggior parte delle risposte di errore usa questa forma JSON compatibile con OpenAI: 
{
  "error": {
    "message": "Descriptive error message",
    "type": "orcarouter_api_error",
    "code": "model_not_found"
  }
}
type è una categoria ampia, code è un identificatore specifico. Alcuni fallimenti fast-path (in particolare i 429 a livello di workspace) restituiscono solo uno status code HTTP con gli header rilevanti e nessun corpo JSON.

​
Codici di stato HTTP

StatusSignificatoCausa tipica
400Bad requestParametri non validi, campi obbligatori mancanti, violazione dello schema
401UnauthorizedChiave API mancante o non valida
403ForbiddenQuota insufficiente, oppure la chiave non può chiamare questo modello
404Not foundModello o endpoint inesistente
429Too many requestsLimite di velocità raggiunto — vedi Limiti di velocità. La risposta include sempre un header Retry-After.
500Internal errorBug lato OrcaRouter
502Upstream errorTutti i provider upstream hanno fallito (inclusa qualunque catena di fallback)
503Service unavailableIl modello richiesto è temporaneamente non disponibile upstream

​
Tipi di errore che puoi vedere in error.type

error.typeDa dove proviene
orcarouter_api_errorFallimenti lato gateway (auth, quota, rate-limit, interni)
upstream_errorIl provider upstream ha restituito un errore o è andato in timeout
openai_errorErrore upstream OpenAI-compat preservato testualmente
claude_errorErrore upstream Anthropic preservato testualmente
gemini_errorErrore upstream Gemini preservato testualmente

​
Codici di errore che puoi vedere in error.code

Questi sono codici emessi dal gateway per fallimenti che originano in OrcaRouter (non dall’upstream):
error.codeHTTPSignificato
insufficient_user_quota403Credito dell’account esaurito. Ricarica.
model_not_found503Questo modello non è disponibile per il tuo account.
model_price_error400Il prezzo per questo modello non è configurato. Contatta il supporto.
api_not_implemented400Endpoint od operazione non supportata per il modello scelto.
bad_request_body400Il corpo della richiesta non è stato analizzato.
prompt_blocked400La policy di sicurezza del provider ha bloccato il prompt prima della generazione.
sensitive_words_detected400Il filtro di contenuti sensibili ha rifiutato il prompt.
Se devi distinguere programmaticamente, fai match prima su error.code (specifico) e fai fallback su error.type (categoria ampia).

​
Errori in streaming

Gli errori durante una risposta in streaming non possono usare status code HTTP (lo status è stato inviato all’apertura dello stream). Il formato dipende dall’endpoint:

​
/v1/chat/completions e /v1/responses (compatibile OpenAI)

L’errore arriva come chunk data: {...} in-band: 
data: {"error":{"message":"...","type":"upstream_error","code":""}}

data: [DONE]
Analizza ogni chunk data: come JSON; se ha un campo error, tratta lo stream come fallito.

​
/v1/messages (compatibile Anthropic)

Anthropic usa eventi SSE con nome. Un fallimento dello stream arriva come: 
event: error
data: {"type":"error","error":{"type":"overloaded_error","message":"..."}}
Lo stream termina con event: message_stop (o viene troncato) dopo l’evento di errore.

​
Errori di fallback

Quando extra_body.models è impostato e tutti i modelli nella catena falliscono, ricevi un 502 con dettagli sull’ultimo errore upstream. Gli header di risposta X-Orca-Fallback-Level e X-Orca-Fallback-Model indicano quale fallback era in tentativo quando la catena si è esaurita. Vedi Header di risposta.