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

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")

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:

Primo tentativo: attendere 1 secondo
Secondo tentativo: attendere 2 secondi
Terzo tentativo: attendere 4 secondi
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.