La gestione degli errori di CometAPI è più semplice quando separi problemi di struttura della richiesta, problemi di autenticazione, errori di percorso e guasti della piattaforma risolvibili con retry. Usa la combinazione di stato HTTP, error.code e error.message per decidere se correggere la richiesta o ritentare.
Triage rapido
Error envelope
Molti errori di CometAPI usano un corpo di errore come questo:
Alcune risposte lasciano code vuoto. Quando lo stato è 500, considera error.code e error.message come il segnale decisivo.
400 Bad Request
Un 400 di solito significa che il corpo della richiesta non ha superato la validazione prima che la richiesta potesse essere elaborata normalmente.
Cause comuni:
- Campi obbligatori mancanti come
model
- Struttura JSON non valida
- Invio di un campo con il tipo sbagliato
- Riutilizzo di parametri specifici del provider che l’endpoint selezionato non accetta
Parti da una richiesta minima sicuramente valida, poi aggiungi di nuovo i campi opzionali uno alla volta. Confronta il payload con lo schema dell’endpoint nella documentazione di riferimento dell’API.
Usa una richiesta minima come questa:
Sostituisci your-model-id con un qualsiasi model ID attuale dalla pagina Modelli di CometAPI.
Non dare per scontato che ogni richiesta chat malformata restituisca 400. Campi chat obbligatori mancanti come messages possono anche emergere come 500 con error.code: invalid_request.
500 Internal Server Error
La maggior parte delle risposte 500 indica un errore della piattaforma o del provider. Per Chat Completions, alcune richieste malformate possono anche emergere come 500 pur includendo error.code: invalid_request.
Un esempio è una richiesta che omette messages:
Se una risposta 500 ha error.code: invalid_request, trattala come un problema della richiesta:
- Correggi il corpo della richiesta.
- Confronta il payload con lo schema dell’endpoint.
- Riprova solo dopo aver corretto il payload.
Se una risposta 500 non indica una richiesta non valida, conserva il request id e usa backoff.
401 Invalid Token
Un errore del token di solito si presenta così:
Cosa controllare:
- L’header deve essere esattamente
Authorization: Bearer $COMETAPI_KEY.
- Assicurati che la tua app non stia caricando una chiave vecchia da
.env, dalla cronologia della shell o da un archivio di secret distribuito.
- Se una chiave fallisce e un’altra chiave funziona sulla stessa request, considera questo un problema di token, non un problema di endpoint.
403 Forbidden
403 è nella maggior parte dei casi una di queste situazioni:
- La request è bloccata da una regola lato piattaforma come il filtro WAF
- Al token o alla route non è consentito usare il model richiesto o la forma della request richiesta
- Il model scelto rifiuta uno dei parametri avanzati che hai passato
Cosa fare per prima cosa:
- Riprova con una request di testo molto semplice su un model sicuramente funzionante.
- Rimuovi i campi avanzati e i parametri specifici del provider, poi riaggiungili gradualmente.
- Se la risposta include un request id, conservalo prima di contattare il supporto.
Se il messaggio menziona termini interni come group o channel, considerali come dettagli di instradamento, non come la prima cosa da diagnosticare lato client. La soluzione pratica resta comunque validare prima il token, il model e la forma della request.
URL base errato o path errato
Su Comet, un errore nel path può manifestarsi come:
- Un reindirizzamento
- Una risposta HTML non JSON se il tuo client segue i reindirizzamenti
- Un errore di parsing all’interno del tuo SDK
- Una request che non raggiunge mai correttamente il layer API
Usa esattamente questo URL base:
Controlli consigliati:
- Conferma che l’URL base includa
/v1.
- Conferma che il path dell’endpoint corrisponda esattamente alla documentazione.
- Disabilita il follow automatico dei redirect durante il debug dei problemi di path.
413 Request Entity Too Large
Se vedi 413, trattalo prima di tutto come un problema di dimensione della request. I sospetti più comuni sono:
- Payload base64 di grandi dimensioni
- Immagini o audio troppo grandi incorporati inline
- Body multipart o JSON molto grandi
Cosa fare:
- Riduci o comprimi il contenuto allegato.
- Suddividi i lavori grandi in request più piccole.
- Non presumere che la lunghezza del solo testo semplice sia l’unica causa.
429 Too Many Requests
Tratta 429 come ritentabile:
- Usa exponential backoff con jitter.
- Riduci la concorrenza nei burst.
- Mantieni attivo il logging delle request così puoi vedere quale route e quale model si saturano per primi.
Per un pattern di retry riutilizzabile, vedi l’esempio di backoff in Chat Completions.
503, 504, and 524
Questi status sono errori lato server o della classe timeout.
Indicazioni pratiche:
503: route o servizio del provider temporaneamente non disponibile504 e 524: errori della classe timeout tra la piattaforma, l’edge o il servizio del provider
Cosa fare:
- Riprova con backoff.
- Conserva il
request id, l’endpoint, il model e il timestamp.
- Se lo stesso errore si ripete in più retry, contatta il supporto con questo contesto.
Prima di contattare il supporto
Acquisisci prima questi dettagli:
- Metodo HTTP
- Percorso dell’endpoint
- Model ID
- JSON del body della richiesta sanitizzato (questo è l’unico elemento più utile per la maggior parte delle chiamate API)
- Parametri di query, se la richiesta che fallisce li utilizzava
- Body della risposta esatto, se il tuo client lo ha acquisito
- Stato HTTP completo
- L’esatto
error.message
- Qualsiasi
request id
- Timestamp approssimativo
- Se la stessa richiesta funziona con un altro model o un altro token
Se la route che fallisce accetta upload di file (modifica di immagini, upload audio, generazione video, ecc.) invece di un semplice body JSON, invia il payload equivalente che è stato inviato:
- Nomi dei campi e valori di testo che hai inviato insieme al file
- Nome del file, tipo di file e dimensione approssimativa del file
- Se il file è stato caricato direttamente, referenziato tramite URL o incorporato come base64
Il modo più efficace per riprodurre un bug è il payload della richiesta sanitizzato esatto. Per la maggior parte delle chiamate API, significa il JSON grezzo del body della richiesta. Per le route con upload di file, significa l’elenco dei campi più i metadati del file.
