Codici di errore e gestione

Risolvi i problemi delle richieste CometAPI non riuscite con indicazioni verificate per errori 400, 401 e di percorso, oltre a suggerimenti pratici per gestire 403, 429 e gli errori della classe timeout.

La gestione degli errori di CometAPI è più semplice quando separi problemi di richiesta, problemi di autenticazione e problemi della piattaforma che possono essere ritentati. Questa pagina è la guida ufficiale agli errori di CometAPI e si concentra su ciò che puoi verificare prima dal lato client.

Questa guida si basa su verifiche effettuate in tempo reale sull’attuale API di CometAPI. Abbiamo verificato direttamente 400, 401 e gli errori di path/base URL. Non abbiamo riprodotto 413, 429, 500, 503, 504 o 524 in test delimitati, quindi le indicazioni per questi stati sono intenzionalmente prudenti.

​

Triage rapido

Status	Cosa significa di solito	Ritentare?	Prima azione
400	La validazione della richiesta non è riuscita prima che la richiesta venisse instradata correttamente.	No	Valida model, messages, la struttura JSON e i tipi dei campi.
401	La chiave API è mancante, malformata o non valida.	No	Controlla Authorization: Bearer <COMETAPI_KEY>.
403	L’accesso è stato bloccato oppure la richiesta corrente non era consentita.	Di solito no	Riprova con una richiesta sicuramente valida e rimuovi prima i campi specifici del model.
Path mistake	Base URL errato o path dell’endpoint errato. Su Comet questo può apparire come un reindirizzamento 301 o HTML, non come un pulito 404 JSON.	No	Usa esattamente https://api.cometapi.com/v1 e disabilita il follow automatico dei redirect durante il debugging.
429	Rate limiting o saturazione temporanea.	Sì	Usa exponential backoff con jitter.
500, 503, 504, 524	Errore della piattaforma o della classe timeout.	Sì	Riprova con backoff e conserva il request id.

​

Error Envelope

L’attuale Error Envelope JSON restituito da CometAPI ha questo aspetto:

{
	"error": {
		"code": "",
		"message": "...",
		"type": "comet_api_error"
	}
}

Molti messaggi di errore osservati dal vivo includono anche un request id all’interno di error.message. Salva quel valore quando hai bisogno di supporto.

​

400 Bad Request

Ciò che abbiamo osservato dall’API live quando model era omesso:

{
	"error": {
		"code": "",
		"message": "model name is required (request id: ...)",
		"type": "comet_api_error"
	}
}

In pratica, 400 di solito significa che il body della richiesta non ha superato la validazione prima che la piattaforma potesse instradarla al provider del model.

Cause comuni:

• Campi obbligatori mancanti come model o messages
• Struttura JSON non valida
• Invio di un campo con il tipo errato
• Riutilizzo di parametri specifici del provider che l’endpoint selezionato non accetta

Cosa fare:

1. Parti da una richiesta minima sicuramente valida.
2. Riaggiungi i campi opzionali uno alla volta.
3. Confronta il body della richiesta con lo schema dell’endpoint nel riferimento API.

Esempio minimo sicuramente valido:

{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}

Sostituisci your-model-id con qualsiasi ID di model attuale dalla pagina Models di CometAPI.

​

401 Invalid Token

Ciò che abbiamo osservato dall’API live con una chiave non valida:

{
	"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 un archivio di secret distribuito.
3. Se una chiave fallisce e un’altra funziona sulla stessa richiesta, trattalo come un problema di token, non come un problema dell’endpoint.

​

403 Forbidden

Non abbiamo riprodotto un 403 stabile in test circoscritti, quindi evita di trattare un singolo vecchio template di messaggio come se spiegasse l’intera situazione.

Nella documentazione attuale di Comet, 403 viene discusso più spesso come una di queste situazioni:

• La richiesta è bloccata da una regola lato piattaforma, come un filtro WAF
• Il token o la route non sono autorizzati a usare il model richiesto o la forma della richiesta
• Il model scelto rifiuta uno dei parametri avanzati che hai passato

Cosa fare per prima cosa:

1. Riprova con una richiesta testuale molto semplice verso un model sicuramente 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 correzione pratica resta comunque validare prima il token, il model e la forma della richiesta.

​

URL base errato o path errato

Questa è l’area in cui la vecchia pagina era meno accurata.

Nei controlli eseguiti sugli endpoint Comet attuali:

• L’invio di una richiesta a https://api.cometapi.com/chat/completions ha restituito un redirect 301 verso https://www.cometapi.com/chat/completions
• L’invio di una richiesta a una route API fittizia come https://api.cometapi.com/v1/not-a-real-endpoint ha anch’esso restituito un redirect 301 verso https://www.cometapi.com/v1/not-a-real-endpoint

Questo significa che 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 richiesta che non raggiunge mai correttamente il layer API

Usa esattamente questo URL base:

https://api.cometapi.com/v1

Controlli consigliati:

1. Conferma che l’URL base includa /v1.
2. Conferma che il path dell’endpoint corrisponda esattamente alla documentazione.
3. Disabilita il follow automatico dei redirect durante il debug dei problemi di path.

​

413 Request Entity Too Large

Non abbiamo riprodotto un 413 in un test circoscritto, nemmeno con un body di richiesta JSON sovradimensionato da 8 MiB, quindi la vecchia spiegazione secondo cui il prompt era troppo lungo era troppo limitata.

Se vedi effettivamente un 413, trattalo prima di tutto come un problema di dimensione della richiesta. 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 i contenuti allegati.
2. Suddividi i job di grandi dimensioni in richieste più piccole.
3. Non dare per scontato che la lunghezza del solo testo semplice sia l’unica causa.

​

429 Too Many Requests

Non abbiamo riprodotto un 429 durante una prova di concorrenza circoscritta con 24 richieste parallele GET /v1/models, quindi la soglia esatta dipende chiaramente dalla route, dal model e dallo stato attuale della piattaforma.

Tratta 429 come ritentabile:

1. Usa exponential backoff con jitter.
2. Riduci la concorrenza nei burst.
3. Mantieni attivo il logging delle richieste così da poter vedere quale route e quale model saturano per primi.

Per un pattern di retry riutilizzabile, vedi l’esempio di backoff in Chat Completions.

​

500, 503, 504, e 524

Non abbiamo riprodotto questi status in test circoscritti. Dovrebbero essere documentati come errori lato server o timeout, non come errori dell’utente.

Indicazioni pratiche:

• 500: errore interno della piattaforma o lato provider
• 503: route o servizio del provider temporaneamente non disponibile
• 504 e 524: errori di tipo timeout tra la piattaforma, l’edge o il servizio del provider

Cosa fare:

1. Riprova con backoff.
2. Conserva il request id, l’endpoint, il model e il timestamp.
3. Se lo stesso errore si ripete dopo più tentativi, contatta il supporto con questo contesto.

​

Prima di contattare il Supporto

Raccogli prima questi dettagli:

• Metodo HTTP
• Percorso dell’endpoint
• Nome del modello
• JSON del body della richiesta sanitizzato (questo è l’elemento più utile nella 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
• Il valore esatto di error.message
• Qualsiasi request id
• Timestamp approssimativo
• Se la stessa richiesta funziona con un altro modello o un altro token

Se la route che fallisce accetta upload di file (modifica di immagini, upload di audio, generazione video, ecc.) invece di un semplice body JSON, invia il payload equivalente effettivamente inviato:

• Nomi dei campi e valori testuali inviati 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ù rapido per riprodurre un bug è avere il payload della richiesta esatto e sanitizzato. 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.

Questo riduce significativamente i tempi di risposta del supporto.