Gestione degli errori

Formato unificato di risposta agli errori

Tutti gli errori API restituiscono un formato JSON unificato:

JSON

{
  "code": 2010,
  "status": "error",
  "message": "You don't have enough credit to create this task",
  "suggestion": "Please purchase more credit",
  "request_id": "req_abc123"
}

Campo	Digitare	Descrizione
code	intero	Codice errore
status	stringa	Esito della richiesta; vale `error` quando la richiesta non va a buon fine
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à o limite di concorrenza superato. Riduci la frequenza delle tue richieste o riprova più tardi
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`
1007	Limite di velocità superato	Riduci la frequenza delle richieste e implementa i nuovi tentativi con backoff esponenziale
2000	Limite di concorrenza superato	Attendi che un’attività della stessa categoria venga completata prima di crearne altre, oppure attendi il tempo indicato dall’intestazione di risposta `Retry-After`. Consulta Limiti di velocità
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.