Vai al contenuto principale

Documentation Index

Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt

Use this file to discover all available pages before exploring further.

La gestione degli errori di CometAPI è più semplice quando separi problemi nella struttura della richiesta, problemi di autenticazione, errori di path e guasti della piattaforma ritentabili. Usa la combinazione di stato HTTP, error.code e error.message per decidere se correggere la richiesta o riprovarla.

​
Triage rapido

StatusCosa significa di solitoRiprovare?Prima azione
400La validazione della richiesta è fallita prima che la richiesta venisse elaborata normalmente.NoConvalida model, messages, la struttura JSON e i tipi dei campi.
401La chiave API è mancante, malformata o non valida.NoControlla Authorization: Bearer <COMETAPI_KEY>.
403L’accesso è stato bloccato oppure la richiesta corrente non era consentita.Di solito noRiprova con una richiesta sicuramente valida e rimuovi prima i campi specifici del modello.
Path mistakeURL di base errato o path dell’endpoint errato. Su Comet questo può apparire come un reindirizzamento 301 o HTML, non come un 404 JSON pulito.NoUsa esattamente https://api.cometapi.com/v1 e disattiva il follow automatico dei redirect durante il debug.
429Rate limiting o saturazione temporanea.SìUsa exponential backoff con jitter.
500 with error.code: invalid_requestUna richiesta malformata è emersa tramite una risposta con stato di errore del server.NoCorreggi il corpo della richiesta prima di riprovare.
500, 503, 504, 524Errore della piattaforma, del provider o classe di timeout.SìRiprova con backoff e conserva il request id.

​
Error envelope

Molti errori di CometAPI usano un corpo di errore come questo: 
{
	"error": {
		"message": "...",
		"type": "comet_api_error",
		"param": "",
		"code": "invalid_request"
	}
}
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 riaggiungi 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: 
{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}
Sostituisci your-model-id con qualsiasi model ID corrente dalla pagina dei modelli CometAPI. Non dare per scontato che ogni richiesta chat malformata restituisca 400. La mancanza di campi chat obbligatori come messages può 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: 
{
	"error": {
		"message": "field messages is required (request id: ...)",
		"type": "comet_api_error",
		"param": "",
		"code": "invalid_request"
	}
}
Se una risposta 500 ha error.code: invalid_request, trattala come un problema della richiesta:
  1. Correggi il corpo della richiesta.
  2. Confronta il payload con lo schema dell’endpoint.
  3. Riprova solo dopo aver corretto il payload.
Se una risposta 500 non indica una richiesta non valida, conserva il request id e usa il backoff.

​
401 Invalid Token

Un errore del token di solito appare così: 
{
	"error": {
		"code": "",
		"message": "invalid token (request id: ...)",
		"type": "comet_api_error"
	}
}
Cosa controllare:
  1. L’header deve essere esattamente Authorization: Bearer <COMETAPI_KEY>.
  2. Assicurati che la tua app non stia caricando una vecchia chiave da .env, dalla cronologia della shell o da uno secret store distribuito.
  3. Se una chiave fallisce e un’altra funziona sulla stessa request, trattalo come un problema di token, non come un problema di endpoint.

​
403 Forbidden

403 corrisponde più spesso a una di queste situazioni:
  • La request è bloccata da una regola lato piattaforma come il filtraggio WAF
  • Il token o la route non sono autorizzati a usare il model richiesto o la forma della request
  • Il model scelto rifiuta uno dei parametri avanzati che hai passato
Cosa fare per prima cosa:
  1. Riprova con una semplice request di testo verso un model noto e funzionante.
  2. Rimuovi i campi avanzati e i parametri specifici del provider, poi riaggiungili gradualmente.
  3. Se la risposta include un request id, conservalo prima di contattare il supporto.
Se il messaggio menziona termini interni come group o channel, trattali come dettagli di instradamento, non come la prima cosa da diagnosticare dal 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 redirect
  • Una risposta HTML non JSON se il tuo client segue i redirect
  • Un errore di parsing all’interno del tuo SDK
  • Una request che non raggiunge correttamente il livello API
Usa esattamente questo URL base: 
https://api.cometapi.com/v1
Controlli consigliati:
  1. Verifica che l’URL base includa /v1.
  2. Verifica che il path dell’endpoint corrisponda esattamente alla documentazione.
  3. Disabilita il follow automatico dei redirect mentre esegui il debug di 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:
  1. Riduci o comprimi il contenuto allegato.
  2. Suddividi i job grandi in request più piccole.
  3. Non dare per scontato che la lunghezza del solo testo semplice sia l’unica causa.

​
429 Too Many Requests

Tratta 429 come ripetibile:
  1. Usa exponential backoff con jitter.
  2. Riduci la concorrenza dei burst.
  3. Mantieni attivo il logging delle request così puoi vedere quale route e quale model si saturano per primi.
Per uno schema 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 disponibile
  • 504 e 524: errori della classe timeout tra la piattaforma, l’edge o il servizio del provider
Cosa fare:
  1. Riprova con backoff.
  2. Conserva il request id, endpoint, model e timestamp.
  3. Se lo stesso errore si ripete in più retry, contatta il supporto con questo contesto.

​
Prima di contattare il supporto

Raccogli 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 ha fallito 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 ha fallito accetta upload di file (modifica di immagini, upload di 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, questo significa il raw request body JSON. Per le route di upload di file, significa l’elenco dei campi più i metadati del file.
Questo riduce significativamente i tempi di risposta del supporto.