# Gestione degli errori

## Formato unificato di risposta agli errori

Tutti gli errori API restituiscono un formato JSON unificato:

```json
{
  "code": 2010,
  "message": "Insufficient credits",
  "suggestion": "Please top up your account at https://platform.tripo3d.ai",
  "request_id": "req_abc123"
}
```

| Campo | Digitare | Descrizione |
| :-: | :-: | :-: |
| code | intero | Codice errore |
| message | stringa | Descrizione dell'errore |
| suggestion | stringa | Correzione suggerita |
| request_id | stringa | Identificatore di richiesta univoco per la risoluzione dei problemi |

## Codici di stato HTTP

| Codice di stato | Significato | Descrizione |
| :-: | :-: | :-: |
| 200 | Successo | La richiesta è stata elaborata con successo |
| 400 | Parametri non validi | I parametri richiesti mancano o non sono corretti |
| 401 | Non autenticato | API Key manca o non è valido |
| 403 | Autorizzazioni insufficienti | Non hai i permessi per accedere alla risorsa oppure i tuoi crediti sono insufficienti |
| 404 | Risorsa non trovata | L'attività o la risorsa richiesta non esiste |
| 429 | Troppe richieste | Limite di velocità superato. Riduci la frequenza delle tue richieste |
| 500 | Errore di servizio | Errore interno del server. Riprova più tardi |

## Riferimento al codice di errore

| Codice errore | Significato | Gestione consigliata |
| :-: | :-: | :-: |
| 1000 | API Key non valido | Controlla se API Key è corretto o è stato cancellato |
| 1001 | Non autorizzato | Controlla se l'intestazione della richiesta include `Authorization` |
| 2000 | Limite di velocità superato | Riduci la frequenza delle richieste e implementa i nuovi tentativi con backoff esponenziale |
| 2002 | Parametro di richiesta non supportato | Controlla se i nomi e i valori dei campi del corpo della richiesta corrispondono alla documentazione |
| 2003 | File di input vuoto | Conferma che il file caricato non è vuoto e utilizza un formato valido |
| 2004 | Tipo di file non supportato | Controlla se il formato file è nell'elenco supportato |
| 2008 | Violazione delle norme sui contenuti | Modificare il contenuto immesso per evitare parole o immagini proibite |
| 2010 | Crediti insufficienti | Ricarica crediti nella console |
| 2015 | Versione deprecata | Aggiorna all'ultima versione API |
| 2018 | Modello troppo complesso | Ridurre la complessità o il numero di poligoni del modello di input |

## Esempi di gestione degli errori

### Python

```python
import time
import requests

def call_api_with_retry(url, headers, payload=None, max_retries=3):
    for attempt in range(max_retries):
        if payload:
            response = requests.post(url, headers=headers, json=payload)
        else:
            response = requests.get(url, headers=headers)

        if response.status_code == 200:
            return response.json()

        if response.status_code == 429:
            wait = 2 ** attempt
            print(f"Rate limit triggered. Retrying in {wait} seconds...")
            time.sleep(wait)
            continue

        error = response.json()
        raise Exception(
            f"API error [{error['code']}]: {error['message']} "
            f"(suggestion: {error.get('suggestion', 'none')})"
        )

    raise Exception("Maximum retry attempts exhausted")
```

### JavaScript

```javascript
async function callApiWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.ok) {
      return await response.json();
    }

    if (response.status === 429) {
      const wait = 2 ** attempt * 1000;
      console.log(`Rate limit triggered. Retrying in ${wait / 1000} seconds...`);
      await new Promise(resolve => setTimeout(resolve, wait));
      continue;
    }

    const error = await response.json();
    throw new Error(
      `API error [${error.code}]: ${error.message} (suggestion: ${error.suggestion || "none"})`
    );
  }

  throw new Error("Maximum retry attempts exhausted");
}
```

## Riprova i suggerimenti sulla strategia

Per errori ripetibili, come limiti di velocità 429 e errori di servizio 500, utilizza una strategia di backoff esponenziale:

1. Primo tentativo: attendere 1 secondo
2. Secondo tentativo: attendere 2 secondi
3. Terzo tentativo: attendere 4 secondi
4. Mantenere il numero massimo di tentativi a 5 o meno

Per gli errori irreversibili, come 400, 401 e 403, genera direttamente un'eccezione e risolvi il problema sottostante.