Errori e limiti di frequenza

Gli errori tornano come JSON nel formato di errore di OpenAI. Il messaggio indica cosa è successo, code è un identificatore stabile leggibile dalla macchina, e a ogni messaggio viene aggiunto un id di richiesta:

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

Includi sempre l'id di richiesta quando contatti il supporto o apri un ticket su Discord. Ci consente di trovare la tua richiesta esatta nei log.

I codici di stato che incontrerai davvero:

Due situazioni molto diverse condividono lo stato 503. La prima è una congestione temporanea:

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

Il codice get_channel_failed (tutti i fornitori occupati) significa che ogni fornitore gratuito di quel modello è momentaneamente limitato in frequenza. Si ripristina da solo in pochi minuti: ritenta o cambia modello. Il codice model_not_found (non offerto qui) significa che il nome del modello stesso non si risolve, e ritentare non aiuterà mai. Controlla gli errori di battitura o cerca il nome attuale nel catalogo.

Tratta il 503 con get_channel_failed come ritentativo o fallback e il 503 con model_not_found come un errore irreversibile nel tuo client.

Un 429 può provenire da diversi livelli:

• Il nostro limite per i modelli gratuiti: 1 richiesta al minuto per modello gratuito per utente. Un limite di equità affinché i pool condivisi sopravvivano alle ore di punta.
• Limiti del fornitore upstream: il fornitore dietro un modello gratuito ha raggiunto il proprio limite ("temporarily rate-limited upstream", cioè temporaneamente limitato a monte).
• Budget giornalieri di token su alcuni pool gratuiti; si azzerano a mezzanotte UTC.
• Limiti di token al minuto che scattano su prompt molto grandi.
• Un limite di concorrenza per utente quando troppe richieste vengono eseguite in parallelo.

I modelli a pagamento non hanno limiti di frequenza imposti da UnoRouter.

Quando scatta il nostro limite di 1 al minuto ottieni header standard di limite di frequenza, così i client possono rallentare con precisione:

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

Retry-After è dinamico: i secondi effettivamente rimasti nella tua finestra, non un 60 fisso. Il messaggio di errore indica anche il gemello a pagamento del modello, che non ha limiti.

Alcuni modelli normalmente a pagamento sono offerti gratuitamente con un limite alla dimensione della richiesta. I prompt troppo grandi ricevono 413 con un messaggio come: Request body too large for gpt-4.1 model. Max size: 8000 tokens.

Il limite si applica solo alla rotta della prova gratuita; il modello a pagamento accetta prompt di lunghezza piena.

Rispetta Retry-After sui 429. Ritenta il 503 get_channel_failed dopo una breve attesa, o ripiega su un altro modello. Non ritentare gli errori di classe 400, sono deterministici.

Le richieste fallite e rifiutate non vengono addebitate: qualsiasi blocco preventivo sul tuo saldo viene rimborsato quando la richiesta va in errore.