> ## 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.

# Gestire i codici di errore

> Usa questa guida per classificare le risposte di errore di CometAPI e applicare passaggi di retry o correzione per i comuni errori di richiesta.

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

| Status                                   | Cosa significa di solito                                                                                                                               | Retry?       | Prima azione                                                                                                          |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------ | --------------------------------------------------------------------------------------------------------------------- |
| `400`                                    | La validazione della richiesta non è riuscita prima che la richiesta venisse elaborata normalmente.                                                    | No           | Convalida `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 o la richiesta corrente non era consentita.                                                                                 | Di solito no | Riprova con una richiesta sicuramente valida e rimuovi prima i campi specifici del modello.                           |
| Path mistake                             | URL di base errato o percorso dell'endpoint errato. Su Comet questo può apparire come un reindirizzamento `301` o HTML, non come un pulito JSON `404`. | No           | Usa esattamente `https://api.cometapi.com/v1` e disabilita i reindirizzamenti con follow automatico durante il debug. |
| `429`                                    | Rate limiting o saturazione temporanea.                                                                                                                | Sì           | Usa exponential backoff con jitter.                                                                                   |
| `500` with `error.code: invalid_request` | Una richiesta malformata è emersa tramite una risposta con stato server.                                                                               | No           | Correggi il corpo della richiesta prima di ritentare.                                                                 |
| `500`, `503`, `504`, `524`               | Errore della piattaforma, del provider o di tipo timeout.                                                                                              | Sì           | Riprova con backoff e conserva il request id.                                                                         |

## Error envelope

Molti errori di CometAPI usano un corpo di errore come questo:

```json theme={null}
{
	"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 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:

```json theme={null}
{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}
```

Sostituisci `your-model-id` con un qualsiasi model ID attuale dalla [pagina Modelli di CometAPI](/it/overview/models).

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`:

```json theme={null}
{
	"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 backoff.

## `401 Invalid Token`

Un errore del token di solito si presenta così:

```json theme={null}
{
	"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 chiave vecchia da `.env`, dalla cronologia della shell o da un archivio di secret distribuito.
3. 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:

1. Riprova con una request di testo molto semplice su 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.

<Warning>
  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.
</Warning>

## 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:

```text theme={null}
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`

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 lavori grandi in request più piccole.
3. Non presumere che la lunghezza del solo testo semplice sia l'unica causa.

## `429 Too Many Requests`

Tratta `429` come ritentabile:

1. Usa exponential backoff con jitter.
2. Riduci la concorrenza nei burst.
3. 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](/api/text/chat).

## `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`, l'endpoint, il model e il timestamp.
3. 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

<Warning>
  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.
</Warning>

Questo riduce significativamente i tempi di risposta del supporto.