Risposta breve: non passare da Claude a GPT per ogni richiesta fallita. Un 401 significa che l’autenticazione va corretta, e un 404 legato al percorso indica che l’URL o l’endpoint devono essere corretti. Un 429 o un 5xx temporaneo possono essere ritentati con backoff; se i retry limitati falliscono comunque, può subentrare un modello di fallback compatibile.
C’è un’eccezione importante: una risposta 500 con error.code: invalid_request è comunque un problema della richiesta. Ritentarla — o inviare lo stesso payload errato a un altro modello — serve solo a nascondere il bug.
Questo articolo è stato verificato il 20 agosto 2026 rispetto alla documentazione di CometAPI su errori, retry, base URL, rate limit e fallback di modello. Copre solo la classificazione degli errori. Per la progettazione delle route, le credenziali del provider e il failover multilivello, usa il tutorial completo sul fallback dei modelli e la guida tecnica al fallback.
Inizia con la decisione: ritentare o fallire
| Stato | Significato abituale | Ritentare? | Fallback? | Prima azione |
|---|---|---|---|---|
| 401 | Chiave mancante o non valida | No | No | Correggi il token Bearer |
| 404 | Percorso o endpoint errato | No | No | Verifica URL di base e route |
| 429 | Rate limit o saturazione | Sì | Dopo retry limitati | Backoff con jitter |
| 500 + invalid_request | Richiesta malformata | No | No | Correggi il payload |
| 500/503/504/524 | Guasto temporaneo di piattaforma/provider | Sì | Dopo retry limitati | Conserva l’ID della richiesta |
La domanda pratica non è “Claude ha fallito?”. È “Un modello diverso potrebbe riuscire senza cambiare la parte non valida di questa richiesta?”. Gli errori di autenticazione e di percorso influenzano la connessione stessa, quindi cambiare modello non può risolverli. I guasti temporanei di capacità e server possono essere specifici della route, quindi un fallback può aiutare.
Leggi l’errore prima di cambiare modello
Usa lo status HTTP insieme a error.code e error.message. Molti errori CometAPI usano una busta come questa:
{
"error": {
"message": "human-readable detail and request id",
"type": "comet_api_error",
"param": "problematic_parameter_or_empty",
"code": "error_code_or_empty"
}
}
Non classificare solo in base alla prima cifra del codice di stato. Un 500 può comunque contenere invalid_request, mentre un percorso CometAPI errato può restituire un redirect o HTML invece di un 404 JSON pulito.
401 Unauthorized: interrompi e correggi l’autenticazione
Un 401 di solito significa che la chiave API è mancante, malformata, scaduta o caricata dall’ambiente sbagliato. L’header deve essere:
Authorization: Bearer $COMETAPI_KEY
Non ritentare e non cambiare modello. Entrambe le route usano la stessa autenticazione rotta. Verifica se il servizio distribuito ha caricato un segreto vecchio, se sono stati aggiunti spazi bianchi alla chiave e se la richiesta raggiunge l’ambiente previsto. Ruota o ricarica la chiave solo tramite il tuo processo di gestione dei segreti.
404 Not Found: correggi l’URL prima del fallback
Per richieste compatibili con OpenAI, usa esattamente questa base URL:
https://api.cometapi.com/v1
Un /v1 mancante, un segmento di percorso duplicato o l’endpoint sbagliato possono produrre 404, un redirect, una risposta HTML o un errore di parsing dell’SDK. Disabilita il follow automatico dei redirect durante il debug e conferma il percorso finale della richiesta rispetto alla reference API.
Se la risposta indica esplicitamente che un modello non è disponibile o non è stato trovato, verifica l’ID del modello nell’attuale CometAPI Models API. Non trattare ogni 404 come indisponibilità del modello. Aggiungi un fallback specifico per il modello solo dopo aver catturato e testato esattamente quel segnale.
429 Too Many Requests: esegui backoff prima del failover
Un 429 è ritentabile. Usa backoff esponenziale con jitter, riduci la concorrenza a raffica e misura quale route è satura. Un retry immediato da ogni worker può trasformare un breve rate limit in un picco di traffico più grande.
Dopo un numero limitato e piccolo di retry, il fallback può essere appropriato quando il modello successivo supporta lo stesso input, il contratto di output e le capacità richieste. Il fallback non è gratuito: aggiunge latenza e può cambiare costo o comportamento, quindi registra quanto spesso viene usato.
Errori 5xx: controlla il codice, poi ritenta
500, 503, 504 e 524 rappresentano comunemente guasti di piattaforma, provider o di tipo timeout. Conserva l’ID della richiesta, l’endpoint, il modello e il timestamp, quindi ritenta con backoff. Se lo stesso errore transitorio persiste oltre il budget di retry, passa alla route compatibile successiva.
Ma ispeziona prima il body. Quando un 500 contiene error.code: invalid_request o invalid_request_error, correggi il body della richiesta e ritenta solo dopo averlo modificato. Le cause comuni includono un campo messages mancante o un parametro specifico del provider che l’endpoint selezionato non accetta.
Usa una piccola policy nel codice
Questo esempio Python mantiene retry e fallback nell’applicazione. Usa una sola chiave CometAPI, la base URL compatibile con OpenAI e variabili d’ambiente per gli ID modello correnti di Claude e GPT. Ritenta solo i guasti transitori, quindi cambia modello dopo che il budget di retry è esaurito.
import os, random, time
from openai import APIError, OpenAI
client = OpenAI(
api_key=os.environ["COMETAPI_KEY"],
base_url="https://api.cometapi.com/v1",
max_retries=0,
)
MODELS = [os.environ["CLAUDE_MODEL"], os.environ["GPT_MODEL"]]
RETRYABLE = {429, 500, 503, 504, 524}
def complete(messages):
for model in MODELS:
for attempt in range(3):
try:
response = client.chat.completions.create(model=model, messages=messages)
return response.choices[0].message.content
except APIError as error:
status = getattr(error, "status_code", None)
code = getattr(error, "code", None)
if status in {401, 404} or code in {
"invalid_request", "invalid_request_error"
}:
raise
if status not in RETRYABLE:
raise
if attempt < 2:
time.sleep(2**attempt + random.random())
continue
break
raise RuntimeError("No configured route completed.")
print(complete([{"role": "user", "content": "Summarize this ticket."}]))
I retry automatici dell’SDK sono disabilitati così che l’applicazione controlli il budget totale di retry e fallback. Senza quel controllo, i retry dell’SDK più i retry dell’applicazione possono moltiplicare le chiamate e ritardare la risposta finale.
Testa la policy senza indovinare
| Segnale simulato | Risultato atteso | Cosa non deve accadere |
|---|---|---|
| 401 | Interrompi immediatamente | Nessun retry e nessuna chiamata GPT |
| 404 | Interrompi immediatamente | Nessun fallback che nasconda un percorso errato |
| 429 | Backoff, poi fallback | Nessuna tempesta di retry immediati |
| 500 + invalid_request | Interrompi immediatamente | Nessuna richiesta rotta duplicata |
| 503/504/524 | Backoff, poi fallback | Nessuna catena illimitata di route |
Questi sono test della policy, non affermazioni sull’affidabilità dei provider in produzione. In staging, inietta lo status e il body dell’errore nel classificatore, verifica il numero e l’ordine delle chiamate e conferma che il tuo errore finale includa ancora il contesto della richiesta originale.
Quando il fallback da Claude a GPT è davvero sicuro
Cambiare famiglia di modelli è sicuro solo quando entrambe le route possono soddisfare lo stesso contratto applicativo. Normalizza i campi di richiesta e risposta, testa l’output strutturato o il comportamento degli strumenti su entrambi i modelli e verifica qualsiasi capacità richiesta per immagini, documenti, contesto o ragionamento prima di abilitare la route.
Il fallback deve anche rispettare gli effetti collaterali. Se la prima route ha già attivato uno strumento, scritto dati o trasmesso una risposta parziale, ripetere ciecamente l’intera richiesta può duplicare azioni o confondere l’utente. Riprendi da un checkpoint o restituisci invece un errore controllato.
Controlli in produzione che mantengono i retry limitati
- Imposta un unico budget totale di latenza. Conta ogni tentativo di retry e fallback sullo stesso limite.
- Limita i retry. Usa backoff con jitter e fermati dopo un piccolo limite configurato.
- Controlla la concorrenza. Riduci le raffiche prima che le richieste escano dall’applicazione.
- Aggiungi un circuit breaker. Interrompi temporaneamente le chiamate a una route che fallisce ripetutamente.
- Registra le decisioni. Cattura status, codice di errore, ID richiesta, modello, tentativo, ritardo e motivo del fallback senza archiviare segreti.
- Traccia il tasso di fallback. Un aumento prolungato è un segnale operativo, non una metrica di successo normale.
Domande frequenti
Un 401 dovrebbe mai attivare un fallback di modello?
No. Correggi o ricarica la chiave API. Un modello diverso chiamato attraverso la stessa credenziale non valida fallirà per lo stesso motivo.
Un 404 dovrebbe attivare il fallback?
Non per impostazione predefinita. Correggi prima l’URL di base o l’endpoint. Solo un segnale di indisponibilità del modello verificato separatamente dovrebbe entrare nel classificatore di fallback.
Quante volte dovrei ritentare un 429?
Usa un limite piccolo definito dall’applicazione che si adatti al budget di latenza lato utente. Esegui backoff con jitter e riduci la concorrenza; non ritentare immediatamente o indefinitamente.
Tutti gli errori 5xx sono ritentabili?
No. Le risposte 500, 503, 504 e 524 temporanee sono candidate al retry, ma un 500 con invalid_request deve fallire duramente finché il payload non viene corretto.
Claude e GPT possono usare la stessa richiesta invariata?
Solo per i campi condivisi che la tua applicazione ha testato. Parametri specifici del provider, formati degli strumenti, output strutturati e input multimodali possono richiedere adapter. Un semplice cambio di ID modello non prova la compatibilità.
Dove si trova l’implementazione completa del fallback?
Consulta How to Build Robust LLM Model Fallback Strategies per l’architettura più ampia e la guida al fallback dei modelli CometAPI per i dettagli di implementazione.
Rendi il classificatore di errori il gatekeeper
Il fallback automatico è utile quando è ristretto e osservabile. Lascia che errori di autenticazione, percorso e richieste malformate falliscano rumorosamente. Ritenta rate limit e guasti temporanei del server con backoff, quindi passa a una route compatibile solo dopo che il budget di retry è stato speso. Questa policy trasforma il fallback in un controllo di affidabilità invece che in un modo per nascondere bug di configurazione.