Errori API: cause e soluzioni
Ogni articolo parte dalla risposta e include un comando per confermare tu stesso la causa. I messaggi di errore sono lasciati in inglese, così come compaiono nel tuo terminale.
Unexpected token '<' quando chiami un'API compatibile con OpenAIIl tuo client ha ricevuto HTML dove si aspettava JSON. Quasi sempre alla base URL manca /v1, oppure lo contiene due volte. Come verificarlo con un solo comando e come risolverlo.401 invalid API key: quando la chiave sembra giusta ma continua a fallireUn 401 con una chiave appena copiata di solito dipende da spazi invisibili, dall'header sbagliato o da una chiave limitata a modelli che non può raggiungere. Come capire qual è il tuo caso.404 su /v1/chat/completions quando l'endpoint esiste di sicuroRicevere un 404 da un endpoint che sai essere attivo è quasi sempre un GET dove l'API si aspetta un POST, oppure un percorso sbagliato di un segmento. Come distinguerli.Timeout 524 sulle richieste API lungheUn 524 arriva da una CDN posta davanti all'API, non dal modello. Scatta quando l'origine non invia nulla per troppo tempo, ed è per questo che le richieste in streaming sopravvivono e le altre no.Model not found: quando il nome del modello è quasi giustoQuesto errore significa quasi sempre che il nome del modello non corrisponde esattamente o che la tua chiave non ha accesso a quel modello. Come elencare ciò che puoi davvero chiamare.Un 429 da un gateway API può significare due cose diverseUn gateway restituisce 429 sia quando il saldo è finito sia quando l'upstream è sovraccarico. Uno vale la pena ritentarlo, l'altro mai. Come distinguerli dal corpo della risposta.Errore CORS chiamando un'API di IA dal browserL'errore CORS è il sintomo. Il vero problema è che una richiesta dal browser consegna la tua chiave API a ogni visitatore. Cosa fare invece, e perché nessuna impostazione degli header lo risolve.400 forzando una chiamata a uno strumento su un modello di ragionamentoImpostare tool_choice su any o tool viene rifiutato dai modelli che ragionano sempre prima di rispondere. Cosa inviare invece, e quali altri parametri questi modelli rifiutano.Le richieste muoiono esattamente a 100 secondi dietro CloudflareUna generazione lunga fallisce quasi esattamente a 100 secondi con un 524 o uno stream interrotto. Quel numero è un limite del proxy Cloudflare, non del tuo server. Come confermarlo e i tre modi per aggirarlo.Il modello restituisce una stringa vuota ma ti viene comunque addebitatoLa risposta arriva con HTTP 200, content è una stringa vuota e il log di utilizzo mostra token di output addebitati. Sui modelli di ragionamento si tratta quasi sempre di max_tokens esaurito prima che venga prodotto testo visibile.Una risposta in streaming si interrompe a metà fraseI token arrivano, poi smettono di arrivare, e non viene sollevato alcun errore. La differenza tra uno stream completato e uno interrotto è una sola riga nel corpo SSE, e la maggior parte del codice client non la controlla mai.Un modello che ieri funzionava ora fallisce per tutti nello stesso gruppo di chiaviUn modello che funzionava inizia a restituire errori per tutte le chiavi di un gruppo, mentre gli altri gruppi non ne risentono. È instradamento, non il modello: un solo account upstream difettoso può mettere fuori uso un intero gruppo.La fattura è più alta di quanto giustifichi il numero di tokenI totali dei token registrati sembrano modesti, ma l'addebito no. Sui modelli della famiglia Claude la causa abituale è la direzione della cache: una scrittura in cache costa più di un input normale, una lettura ne costa una frazione, e gli stessi token possono differire di dodici volte.Claude Code e Codex hanno bisogno di base URL diverse sullo stesso gatewayLo stesso gateway, la stessa chiave, due agenti di programmazione, e una base URL che funziona in uno fallisce nell'altro. La regola è semplice una volta che sai quale client aggiunge il percorso da solo.405 Method Not Allowed chiamando un'API di IAUn 405 su un endpoint di IA quasi mai significa che il metodo è sbagliato. Significa che il POST è finito in un punto che serve solo pagine, di solito il dominio nudo, perché alla base URL manca /v1. Come confermarlo con un comando.404 su /responses: anche la Responses API ha bisogno del prefisso di versioneI client che passano da chat/completions alla Responses API spesso perdono il prefisso di versione. Il 404 arriva dal bordo della rete, prima che venga eseguito qualsiasi codice dell'API, quindi la chiamata non compare mai nel log di utilizzo.context_length_exceeded: cosa conta davvero per il limiteIl limite copre l'intera conversazione più lo spazio riservato alla risposta, non solo il tuo ultimo messaggio. Perché accorciare il prompt spesso non aiuta, e cosa tagliare invece.529 overloaded_error da Claude: cos'è e cosa fare529 significa che l'upstream è saturo in questo momento. Non è un problema di quota né qualcosa che la tua chiave possa risolvere. Come distinguerlo dal 429, e lo schema di retry che aiuta davvero.401 con una chiave sicuramente corretta: controlla il formato dell'headerUna chiave può essere perfettamente valida e produrre comunque un 401 se l'header è costruito male. I tre modi in cui si sbaglia, e come vedere l'header che il tuo client ha davvero inviato.400 unsupported parameter su un modello di ragionamentoI modelli di ragionamento rifiutano parametri di campionamento che ogni altro modello accetta. Quali togliere, perché il valore predefinito è comunque di solito ciò che volevi, e come mantenere un unico percorso di codice per entrambi i tipi di modello.Utilizzo dei token assente in una risposta in streamingUna risposta in streaming non contiene il conteggio dei token se non lo richiedi. Come attivarlo, dove arriva il frammento finale e cosa fare quando un gateway non lo invia.400 su una chiamata a strumento: ogni tool_use ha bisogno del suo tool_resultL'errore compare un turno dopo lo sbaglio, ed è questo a renderlo confuso. La regola di abbinamento, la regola di ordine e come riprodurlo di proposito per risolverlo una volta per tutte.La modalità JSON restituisce comunque testo che non si riesce ad analizzareresponse_format vincola la forma, non la conclusione. Il troncamento, la mancanza di controllo dello schema e il testo attorno all'oggetto rompono ciascuno l'analisi in modo diverso.La chiamata funziona con curl ma non dalla tua applicazioneStessa chiave, stesso URL, risultato diverso. La differenza sta quasi sempre in qualcosa che curl non fa: un proxy, una variabile d'ambiente obsoleta, una restrizione di IP o una libreria che riscrive la tua richiesta.SSL certificate verify failed chiamando un'API di IAUn errore TLS nel tuo SDK mentre curl funziona è quasi sempre un proxy aziendale o un antivirus che rifirma il traffico. Perché disattivare la verifica è la soluzione sbagliata, e quali sono le tre giuste.socket hang up a metà di una risposta in streamingUno stream che si ferma a metà ti lascia con una risposta parziale e nessun errore dal modello. Come distinguere un'interruzione di rete da un'interruzione lato upstream, e cosa fare in ciascun caso.Claude Code: API Error 400 prompt is too longL'errore cita la richiesta, ma la causa è il contesto accumulato nella sessione: file letti, output degli strumenti e cronologia della conversazione vengono reinviati a ogni turno. Cosa svuotare e cosa tenere.Immagine in input rifiutata da un modello di visioneGli endpoint di visione rifiutano le immagini per quattro motivi distinti che producono errori quasi identici. Come distinguerli prima di metterti a ricodificare.Il prompt di sistema si comporta diversamente a seconda del modelloLe due forme di API dominanti collocano le istruzioni di sistema in posti diversi. Il codice scritto per una si degrada in silenzio sull'altra invece di fallire, il che è peggio di un errore.Leggere correttamente un 429: retry-after e gli header dei limitiLa maggior parte del codice di retry tira a indovinare. La risposta di solito ti dice esattamente quanto aspettare e quale limite hai raggiunto. Come leggerla, e cosa fare quando l'header manca.I modelli di un endpoint personalizzato non compaiono nell'elenco del clientI client desktop costruiscono l'elenco dei modelli in modi diversi, e diversi non chiamano mai /v1/models. Come capire quale tipo hai e cosa fare in ciascun caso.Risposta vuota con finish_reason content_filterUna risposta vuota con content_filter come motivo di fine significa che un sistema di sicurezza l'ha fermata. Come distinguerla da un troncamento e da un vero errore, e quanto ti costa.Gli orari nel log di utilizzo non corrispondono al momento della chiamataUna chiamata che compare a ore di distanza da quando l'hai fatta è quasi sempre una differenza di fuso orario e non un record perso. Come allineare i due prima di segnalare un problema di fatturazione.Addebitato due volte per quella che sembrava una sola richiestaUn timeout lato client non ferma il lavoro già in corso sul server. Lo schema tipico di un doppio addebito accidentale, e le due modifiche che lo evitano.