Limiti di frequenza ed errori
I limiti e il significato di ogni codice di stato.
Un 429 può provenire da diversi livelli:
- Il nostro tetto sui modelli gratuiti: 1 richiesta al minuto, per modello gratuito, per utente.
- Limiti a monte: il provider dietro un modello gratuito ha raggiunto il proprio tetto.
- Budget giornalieri di token su alcuni bacini gratuiti, azzerati a mezzanotte UTC.
- Tetti di token al minuto, attivati da prompt molto grandi.
- Un limite di concorrenza per utente sulle richieste parallele.
I modelli a pagamento non hanno limiti di frequenza imposti da UnoRouter.
Quando scatta il tetto di 1 al minuto ricevi gli header standard di limite di frequenza:
HTTP/1.1 429 Too Many Requests
Retry-After: 38
X-RateLimit-Limit: 1
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1783198478Retry-After indica i secondi rimasti nella tua finestra, non un valore fisso di 60. Il messaggio nomina il modello a pagamento, che non ha limiti.
Alcuni modelli a pagamento sono offerti gratis con un tetto sulla dimensione della richiesta. I prompt troppo grandi restituiscono 413: Request body too large for gpt-4.1 model. Max size: 8000 tokens.
Il tetto vale solo per il percorso gratuito. Il modello a pagamento accetta prompt di lunghezza piena.
Gli errori restituiscono JSON nel formato di errore OpenAI. code è un identificatore stabile. 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 l'id di richiesta nei ticket di supporto. Individua la tua richiesta nei log.
Se stai ancora configurando la chiave o l'URL di base, parti da Avvio rapido
I codici di stato che incontrerai davvero:
| Codice | Significato | Cosa fare |
|---|---|---|
400 | Richiesta non valida: parametro errato oppure prompt bloccato dalla moderazione. | Correggi la richiesta. Riprovare senza modifiche fallisce di nuovo. |
401 | Chiave mancante, non valida, scaduta o disattivata. | Controlla l'header Authorization e la Tokens page. |
402 | Il limite di spesa proprio di questa chiave è esaurito. | Aumenta il limite della chiave o crea una nuova chiave. |
403 | Credito esaurito, modello non consentito per questa chiave oppure IP non in lista consentita. | Ricarica, o controlla le restrizioni di modello e IP della chiave. |
413 | La richiesta supera il tetto di dimensione della prova gratuita del modello. | Accorcia il prompt o passa al modello a pagamento. |
429 | È scattato un limite di frequenza (vedi i tipi qui sotto). | Attendi i secondi di Retry-After, poi ritenta o cambia modello. |
500 | Qualcosa è andato storto da parte nostra o presso il fornitore upstream. | Riprova dopo una breve attesa. Segnala i 500 persistenti. |
503 | Tutti i provider sono occupati, oppure il nome del modello non esiste. | Leggi il messaggio: il sovraccarico passa in pochi minuti, un errore di battitura no. |
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"
}
}get_channel_failed significa che tutti i provider gratuiti per quel modello sono a frequenza limitata. Passa in pochi minuti: riprova o cambia modello. model_not_found significa che il nome non si risolve; riprovare non serve mai. Controlla gli errori di battitura o il catalogo.
Tratta get_channel_failed come ritentabile e model_not_found come errore definitivo.
Un modello sparito sotto carico torna da solo; per essere avvisato appena rientra, osservalo in Notifiche
Se la tua chiave blocca gruppi di provider, esiste un terzo 503 quando solo i tuoi gruppi bloccati sono giù, vedi Blocco gruppi
Rispetta Retry-After sui 429. Riprova i 503 get_channel_failed dopo una breve attesa, oppure cambia modello. Non riprovare gli errori di classe 400.
Le richieste fallite o rifiutate non vengono mai addebitate; il funzionamento di trattenuta e rimborso è spiegato in Account e fatturazione