Ritenti nelle API di IA: come gestire gli errori senza duplicare richieste o costi

Un retry non è una ripetizione innocua

Riprovare una chiamata significa inviare di nuovo una richiesta dopo che un tentativo precedente non ha prodotto una risposta utilizzabile dal client. La difficoltà è che «non ho ricevuto risposta» non equivale necessariamente a «il server non ha elaborato la richiesta». La connessione può interrompersi prima dell’invio, durante la trasmissione oppure dopo che il servizio ha ricevuto ed eseguito la richiesta. In quest’ultimo caso, ripeterla potrebbe avviare una seconda operazione o comportare un secondo addebito, anche se il client ha visto soltanto un errore di rete.

Per questo, una politica utile parte da prima della scelta dell’intervallo tra i tentativi. Occorre sapere quale operazione si sta ripetendo, quale risultato è noto, quale è incerto e quanto sforzo aggiuntivo è consentito. Una nuova richiesta senza effetti esterni e un’operazione che avvia un’attività, consuma risorse o modifica lo stato non comportano lo stesso rischio. Inoltre, recuperare la disponibilità non equivale a garantire che la stessa generazione venga eseguita una sola volta: questa garanzia dipende dalle funzionalità documentate dell’API e dalla progettazione dell’integrazione.

Questa guida presenta decisioni da adattare al fornitore specifico. La documentazione di Kimi e ShareAI qui indicata può servire da riferimento per le rispettive API, ma gli estratti disponibili non confermano codici di errore specifici, intestazioni di attesa o meccanismi di idempotenza. Non bisogna trasferire questi dettagli da un servizio a un altro né presumere che un’API li offra solo perché sono comuni altrove.

Classifica l’errore prima di decidere

Non raggruppare tutte le risposte fallite sotto un’unica regola automatica. Distingui almeno gli errori che indicano un problema di configurazione o di validazione, le risposte legate ai limiti d’uso, le scadenze dei timeout e i problemi di connessione. Questa classificazione è un punto di partenza per l’analisi, non una tabella universale di codici: ogni fornitore definisce le proprie risposte e il loro significato. Consulta la documentazione aggiornata dell’API e registra quali segnali giustificano un’azione in ciascun caso.

Un errore di validazione, per esempio, di solito richiede di correggere la richiesta, non di inviarla di nuovo senza modifiche. Un limite d’uso può consentire di riprovare più tardi, ma è necessario seguire le indicazioni documentate dal servizio. Un timeout o una disconnessione lasciano aperta un’altra domanda: il servizio ha ricevuto la richiesta? Se non è possibile stabilirlo, classifica l’esito come incerto invece di dare per scontato che non ci sia stata alcuna elaborazione. Questa distinzione è particolarmente importante quando l’operazione può comportare costi o effetti duplicati.

La decisione di riprovare dovrebbe considerare anche se il problema sembra temporaneo, se ha senso ripetere la stessa richiesta e se rimangono tempo e tentativi nel budget disponibile. La fonte secondaria che confronta il retry con il passaggio a un altro modello raccomanda di limitare i tentativi agli errori transitori, alle operazioni ripetibili in sicurezza e al budget disponibile. È un criterio generale di progettazione, non una definizione ufficiale degli errori di un fornitore specifico.

Definisci una politica esplicita e limitata

Una politica di retry dovrebbe specificare per iscritto quali errori possono provocare un nuovo tentativo, quante volte è consentito riprovare, quanto può durare l’intero ciclo e cosa fa il client quando raggiunge il limite. Distingui il primo invio dai retry: se imposti un numero massimo di tentativi totali, indica se il conteggio include la richiesta iniziale. Questa precisione evita interpretazioni diverse tra codice, configurazione e metriche.

Il limite di tempo totale —a volte chiamato budget temporale— dovrebbe comprendere l’attesa e le chiamate successive, non soltanto il tempo di connessione di un singolo tentativo. Se il limite scade, non programmare altre ripetizioni anche se non è ancora stato raggiunto il numero massimo di tentativi. Viceversa, raggiungere il massimo deve interrompere la sequenza anche se rimane tempo. In questo modo si evitano cicli illimitati e richieste che continuano a impegnare risorse molto dopo che il chiamante avrebbe potuto usare il risultato.

Non esiste un numero di tentativi o una durata adatti a tutte le API. Giustifica questi parametri in base alla latenza tollerata dall’applicazione, alle indicazioni del fornitore, al costo potenziale dell’operazione e al comportamento misurato durante i guasti. La guida di assistenza di Kimi menziona una strategia di attesa esponenziale e il controllo del numero di richieste; l’estratto disponibile non prescrive valori universali né conferma che la strategia valga per tutti gli errori.

Quando la documentazione di un’API indica un segnale di attesa, verifica che cosa significa e a quali casi si applica, quindi segui le istruzioni del fornitore. Non inventare il nome di un’intestazione né interpretare il segnale di un altro servizio come equivalente. Se un segnale documentato non è stato verificato, il client non dovrebbe fingere di poter dedurre da quel segnale il momento corretto per riprendere.

Attese progressive e variabilità casuale

Un’attesa progressiva aumenta il tempo tra tentativi consecutivi. Può ridurre la pressione causata da chiamate ripetute a brevissima distanza quando un servizio è sovraccarico o sta subendo un’interruzione. La documentazione per la risoluzione dei problemi di Kimi menziona l’attesa esponenziale insieme al controllo del numero di richieste. Questo riferimento conferma che tali concetti sono trattati nella documentazione di Kimi; non definisce una configurazione valida per altre API né dimostra che una specifica attesa sia adatta a tutti i casi.

La variabilità casuale, o jitter, aggiunge variazioni agli intervalli per evitare che molti client, dopo un errore simultaneo, riprendano a chiamare il servizio nello stesso momento. È uno strumento progettuale possibile, non un obbligo universale. Valuta se è compatibile con i segnali pubblicati dal fornitore e con la durata massima dell’operazione. Se esiste un’istruzione di attesa documentata, non sostituirla con una pausa casuale che potrebbe contraddirla.

Documenta i parametri scelti e il motivo di ciascuno: come aumentano le attese, qual è il loro limite, quale variazione viene applicata e come si interrompe la sequenza quando scade il budget. Misura l’effetto usando dati operativi: numero di tentativi per richiesta, successi dopo un retry, durata totale, errori finali e consumo associato, quando è possibile misurarlo. Non trasformare un’indicazione orientativa in un valore universale senza averla testata con il fornitore e il carico effettivi.

Evita i duplicati: idempotenza ed esito incerto

L’idempotenza è una proprietà che permette di ripetere un’operazione senza produrre effetti aggiuntivi, entro le condizioni definite dal sistema. In un’API non basta trovare il termine in una pagina: verifica se il fornitore offre una chiave di idempotenza o un meccanismo equivalente, quali endpoint o operazioni copre, come va inviato, per quanto tempo viene riconosciuto e cosa accade se viene riutilizzato con parametri diversi. Solo la documentazione aggiornata del fornitore può confermare queste garanzie.

Le fonti disponibili non verificano il supporto dell’idempotenza per Kimi o ShareAI. La pagina di ShareAI segnala espressamente che le operazioni di scrittura richiedono attenzione, ma l’estratto non conferma una chiave o una garanzia specifica. Di conseguenza, non si dovrebbe affermare che uno di questi fornitori elimini per impostazione predefinita le richieste duplicate. Se l’API non documenta un meccanismo applicabile, considera una disconnessione successiva all’invio come un esito potenzialmente incerto e verifica se il fornitore offre una procedura di riconciliazione.

Distingui tra il controllo di un’operazione già identificata e l’avvio di una nuova operazione. Se l’API documenta un identificatore consultabile, usalo soltanto secondo l’ambito e il ciclo di vita descritti. Se non esiste un modo documentato per verificare l’esito, l’integrazione dovrà scegliere se fermarsi, segnalare l’incertezza o consentire un nuovo tentativo dichiarandone esplicitamente il rischio. Non promettere un’esecuzione esattamente una volta se non esiste una garanzia verificata che copra il caso reale.

Esempio pratico: la risposta si perde dopo l’invio

Immagina che un’applicazione invii una richiesta di generazione. Il client attende la risposta, ma la connessione si interrompe. Non sa se il server ha ricevuto la richiesta, se ha iniziato a elaborarla o se ha terminato. Invece di ripetere automaticamente, contrassegna il tentativo come incerto e consulta la documentazione di quella API: è disponibile una chiave di idempotenza applicabile? Esiste un modo documentato per verificare lo stato? Quale procedura prevede il fornitore per questo tipo di interruzione? Le risposte determinano l’azione successiva.

Se esiste un meccanismo documentato che copre l’operazione, l’integrazione può ripetere la richiesta o controllarne lo stato seguendo esattamente l’ambito previsto. In caso contrario, non può dedurre dall’errore di trasporto che il servizio non abbia elaborato la richiesta. Il team deve applicare la politica di rischio approvata in precedenza: per esempio, fermarsi e mostrare uno stato in attesa di verifica oppure consentire una ripetizione chiarendo che potrebbe comportare un altro consumo. La scelta appropriata dipende dall’impatto di una duplicazione e dai meccanismi disponibili; non esiste una risposta universale.

Se il fornitore restituisce una risposta definitiva, il ciclo termina secondo il significato documentato di quella risposta. In caso di successo, non vengono programmati altri tentativi. Se viene confermato un errore temporaneo e la ripetizione è sicura, si verificano di nuovo il limite, il budget e l’intervallo di attesa. Se scade il budget o si raggiunge il numero massimo, la sequenza termina e il sistema registra l’esito finale o incerto. Il contatore non deve essere azzerato soltanto perché è cambiato il processo che gestisce la richiesta.

Testa scenari di errore realistici prima del rilascio

I test dovrebbero verificare sia la decisione di riprovare sia quella di fermarsi. Simula un errore che la configurazione classifica come temporaneo e verifica che il client rispetti il limite. Simula errori persistenti e conferma che non si ripeta all’infinito. Fai scadere il budget temporale quando sarebbero ancora disponibili altri tentativi; poi verifica che il raggiungimento del numero massimo interrompa comunque il ciclo anche se rimane tempo.

Includi una risposta tardiva e una disconnessione subito dopo l’invio. Sono situazioni diverse: la risposta tardiva può arrivare quando il client considera già scaduto il timeout, mentre la disconnessione successiva all’invio lascia incerto lo stato dell’elaborazione. Verifica che l’applicazione non duplichi un’operazione presumendo che entrambe le situazioni significhino «il server non ha fatto nulla». Se il fornitore offre una funzione di idempotenza, i test dovrebbero verificarne l’ambito in un ambiente adeguato e sulla base della documentazione aggiornata, non simulare una garanzia che il servizio non ha promesso.

Aggiungi casi di errore di validazione e di limite d’uso per controllare che una regola generica non venga applicata a tutte le risposte. Se il fornitore pubblica segnali di attesa, testane l’interpretazione documentata. Infine, verifica che i log consentano di ricostruire l’ordine dei tentativi senza conservare inutilmente prompt, risposte o dati sensibili. Gli identificatori di correlazione, il tipo di esito, i tempi e il numero del tentativo sono spesso più utili per la diagnosi che copiare l’intero contenuto della richiesta.

Criteri per portare la politica in produzione

Prima del rilascio, registra quale documentazione hai consultato, quando l’hai verificata e a quale versione o endpoint si applica. Tieni separate le istruzioni del fornitore e le decisioni dell’applicazione: una raccomandazione documentata non sostituisce l’analisi del rischio di duplicazione e una politica locale non dovrebbe essere presentata come una garanzia del servizio.

Dopo il rilascio, controlla i risultati. Un aumento dei tentativi per chiamata, dei cicli esauriti o degli esiti incerti può indicare un peggioramento, una configurazione troppo aggressiva o un cambiamento nel comportamento del servizio. Tratta il fallback —per esempio, l’uso di una rotta alternativa approvata— come una decisione distinta dal retry: la fonte secondaria sulle API di LLM raccomanda di passare soltanto a un’alternativa approvata in precedenza. Prima di attivare un fallback, verifica compatibilità, qualità, privacy e costi; non usarlo per nascondere la possibilità che la chiamata originale sia già stata elaborata.

Infine, misura separatamente il recupero tecnico e la qualità della risposta. Il fatto che una chiamata abbia avuto successo dopo diversi tentativi non dimostra che il contenuto generato sia corretto o appropriato. Una politica robusta limita i danni e chiarisce gli esiti; non sostituisce la valutazione dell’output del modello né le decisioni di sicurezza dell’applicazione.

Continua a esplorare

Correzioni e trasparenza

Se trovi un dato errato o non aggiornato, inviaci la pagina e la fonte da verificare.