Documentazione/Gestione degli errori

Gestione degli errori

Tutti gli errori dell'API seguono un formato coerente. Ecco come gestirli al meglio.

Visualizza il Markdown OpenAPI JSON

Formato della risposta di errore

Quando si verifica un errore, l'API restituisce un oggetto JSON con questa struttura:

json
{
  "error": "Validation Error",
  "message": "The email field is required.",
  "status_code": 422
}

Codici di errore

Codice di statoErroreCausa e soluzione
400 Bad Request JSON malformato o campi obbligatori mancanti. Controlla il corpo della richiesta.
401 Unauthorized Chiave API mancante o non valida. Controlla l'header Authorization .
402 Payment Required Crediti insufficienti. Acquista altri crediti o attendi il reset del limite giornaliero.
422 Validation Error Il formato dell'indirizzo email non è valido. Controlla il valore che stai inviando.
429 Too Many Requests Rate limit superato. Controlla l'header Retry-After e attendi.
500 Internal Server Error Qualcosa è andato storto da parte nostra. Riprova tra qualche secondo. Contatta il supporto se continua a non funzionare.

401 Unauthorized

json
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key",
  "status_code": 401
}

Soluzione: Verifica che l'header Authorization sia formattato correttamente come Bearer YOUR_API_KEY. Controlla la tua chiave nella dashboard.

422 Validation Error

json
{
  "error": "Validation Error",
  "message": "The email field must be a valid email address.",
  "status_code": 422
}

Soluzione: Assicurati che il valore email abbia un formato valido (ad es. user@example.com). Pulisci l'input prima di inviarlo.

429 Too Many Requests

json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please slow down.",
  "status_code": 429,
  "retry_after": 15
}

Soluzione: Attendi il numero di secondi indicato in retry_after prima di riprovare. Vedi Rate limit →

Checklist per la risoluzione dei problemi