Errori dell'API GPT-6 Astra: 15 Problemi Comuni e Come Risolverli
Diagnostica 15 guasti comuni dell'API GPT-6 Astra, inclusi 400, 401, 403, 404, 409, 422, 429, 500, 503, timeout, stato WebSocket, strumenti e streaming.
｜ Source: Elser AI
Il modo più veloce per peggiorare un incidente API è riprovare ogni errore. Uno schema malformato non si risolve con il backoff, e un saldo crediti esaurito non si riprenderà perché un worker ha provato altre dieci volte. Diagnostica gli errori tramite lo stato HTTP, la classe SDK, error.type e soprattutto error.code.
Un gestore di errori sicuro
prova { return await client.responses.create({ model: "gpt-6-astra", input }); } catch (error) { if (error instanceof OpenAI.APIConnectionError) { // Network, proxy, TLS, DNS or firewall path. } else if (error instanceof OpenAI.RateLimitError) { // Inspect code and Retry-After before deciding to retry. } else if (error instanceof OpenAI.APIError) { console.error(error.status, error.message, error.code); } else { lanciare errore; } }
Registra l'ID della richiesta, timestamp e fuso orario, modello, endpoint, stato, codice, numero di tentativi e caratteristiche del payload sanificate. Non registrare mai chiavi API o contenuti riservati del prompt per impostazione predefinita.
## 1. 400 Richiesta Errata
Il payload è malformato o incompatibile: campo errato, input mancante, schema dello strumento non valido, combinazione non supportata o contenuto mal codificato. Leggi il messaggio, confrontalo con il riferimento corrente per le risposte e aggiungi test contrattuali. Non ripetere l'input invariato.
## 2. Errore di autenticazione 401
La chiave o il token non è valido, è scaduto, revocato o inviato in modo errato. Conferma l'iniezione del segreto e l'ambiente del progetto. Ruota le chiavi esposte; non stamparle mai durante il debug.
## 3. 401 Organizzazione o progetto non corretto
Una chiave valida può comunque puntare all'ambito sbagliato. Controlla la configurazione del progetto e qualsiasi header esplicito di organizzazione/progetto. Allinea la chiave, la risorsa e l'ambito di fatturazione.
## 4. 401 IP non autorizzato
La fonte della richiesta non corrisponde alla lista consentita configurata. Invia da un IP di uscita approvato o aggiorna la lista consentita tramite amministrazione autorizzata. Riprovare dalla stessa fonte non serve a nulla.
## 5. 403 Permesso negato o regione non supportata
Il chiamante non ha accesso alla risorsa, al modello o alla regione. Verifica il ruolo del progetto, la disponibilità del modello, la proprietà della risorsa e le regole dei paesi supportati. Non mascherare un problema di autorizzazione come "non trovato" nei log interni.
## 6. 404 Non Trovato
Un identificatore di risposta, conversazione, archivio vettoriale, file o altro è errato, scaduto o inaccessibile. Verifica l'ID esatto e il progetto. Se visibile all'utente, evita di rivelare l'esistenza di risorse al di fuori del suo ambito.
## 7. 409 Conflitto
Un'altra richiesta ha modificato la risorsa contemporaneamente. Ricarica lo stato corrente, riapplica la modifica desiderata sulla nuova versione e utilizza il blocco ottimistico o l'idempotenza. I tentativi immediati e ciechi possono ripetere il conflitto.
## 8. 422 Entità Non Processabile
Il formato è sintatticamente accettabile ma il servizio non può elaborarlo. Verifica dimensioni, codifiche, stato del file e combinazioni di campi. La tabella ufficiale suggerisce di riprovare, ma prima rimuovi le cause deterministiche.
## 9. Limite di richieste o di token 429
Regola il traffico e rispetta `Retry-After` quando presente. Altrimenti utilizza un backoff esponenziale limitato con jitter. Coordina i budget di ripetizione tra i worker in modo che non creino un effetto mandria. Riduci le chiamate ridondanti e i grandi picchi di token.
## 10. 429 `rallenta`
Questo è un segnale di ramp-rate: il traffico è cresciuto troppo rapidamente anche se i limiti principali sembrano sufficienti. Segui `Retry-After`, riduci la frequenza delle richieste, poi aumenta gradualmente. Le attuali linee guida di OpenAI forniscono una regola empirica secondo cui, dopo aver raggiunto un milione di token di input al minuto, la crescita non dovrebbe superare il 50% ogni 15 minuti; l'attivazione effettiva varia in base al modello e alle condizioni.
## 11. Limite di credito, spesa o utilizzo 429
I codici includono `credit_balance_exhausted`, `organization_spend_limit_exceeded`, `project_spend_limit_exceeded` e `organization_usage_limit_exceeded`. Questi richiedono crediti o modifiche ai limiti. Riprovare non può ripristinare l'accesso. Avvisa un proprietario e interrompi subito.
## 12. 500 Errore Interno del Server
Riprova dopo una breve attesa con un budget limitato e controlla la pagina di stato se i fallimenti persistono. Cattura l'ID della richiesta per il supporto. Per un flusso di lavoro che modifica lo stato, riconcilia gli effetti collaterali degli strumenti prima di riprodurre l'intera richiesta.
## 13. Modello 503 sovraccarico
Il tipo/codice documentato è `service_unavailable_error` / `server_is_overloaded`. Rispetta `Retry-After` o riduci la frequenza quando assente. Nota che le attuali linee guida dell'SDK Python distinguono `RateLimitError` per 429 da `InternalServerError` per 503; gestisci entrambi se la tua logica di sovraccarico in precedenza presumeva che ogni problema di capacità fosse 429.
## 14. Errori di connessione o timeout
`APIConnectionError` può indicare problemi di rete, proxy, certificato TLS, DNS o firewall. `APITimeoutError` significa che la scadenza è scaduta. Riprova letture sicure, controlla le impostazioni del proxy aziendale ed evita di disabilitare la verifica TLS. Per le scritture, determina se l'operazione è avvenuta prima di riprovare.
## 15. Stato WebSocket e fallimenti dello streaming
`previous_response_not_found` significa che lo stato di riferimento non può essere risolto; la guida ufficiale dice di reinviare il contesto di input completo con `previous_response_id` impostato su `null`. `websocket_connection_limit_reached` riflette il limite di connessione di 60 minuti; apri una nuova connessione e continua. Gestisci anche gli eventi `response.failed`, `response.incomplete` e di trasporto `error` piuttosto che presumere che la chiusura del socket equivalga al completamento.
## Una matrice di riprova
| Classe | Riprova invariato? | Azione corretta |
| 400/401/403/404 | No | Correggi richiesta, identità, permesso o ID |
| 409 | Dopo la riconciliazione | Ricarica la versione e applica in sicurezza |
| 422 | A volte | Controlla prima la causa deterministica |
| 429 rate/slow_down | Sì, limitato | Rispetta `Retry-After`; backoff e jitter |
| 429 fatturazione/limiti | No | Aggiungi crediti o modifica i limiti approvati |
| 500/503 | Sì, limitato | Backoff, controllo dello stato, preserva ID richiesta |
| Connessione/timeout | Dipende | Riprova letture; riconcilia scritture |
Tentativi di connessione e tempo totale trascorso per i tentativi. Utilizza un interruttore di circuito durante incidenti estesi e un percorso di messaggi non recapitabili per i lavori che necessitano di revisione da parte dell'operatore. I tentativi devono essere osservabili, non nascosti all'interno di cicli annidati di SDK e applicazioni.
## FAQ
### Dovrei riprovare ogni 429?
No. Gli errori di tariffa e rampa possono riprovare dopo il ritardo richiesto; gli errori di credito, spesa e limite di utilizzo richiedono un'azione sull'account.
### Perché registrare l'ID della richiesta?
Consente al supporto e alla tua telemetria di correlare un guasto con una specifica richiesta API senza esporre l'intero payload.
### Posso riprovare una chiamata di strumento scaduta?
Solo dopo aver determinato se ha causato un effetto collaterale. Usa chiavi di idempotenza e riconciliazione read-before-retry.
### Cosa dovrebbero vedere gli utenti?
Un messaggio conciso e attuabile con un'opzione di riprova sicura, ove appropriato. Mantieni stack trace, codici provider e dettagli sensibili nella diagnostica protetta.
## Conclusione
La gestione affidabile degli errori di GPT-6 Astra inizia con la classificazione. Correggi le richieste deterministiche 4xx, distingui la pressione del rate dai limiti di fatturazione, arretra sui fallimenti transitori 5xx, riconcilia le scritture incerte e modella lo streaming come una macchina a stati. Una politica di retry limitata, insieme a una buona telemetria a livello di richiesta, risolve più incidenti di quanto faranno mai i retry indiscriminati.
