Codici di errore

Codici di errore

Errori strutturati

Ogni errore dell’API restituisce la stessa struttura JSON: un oggetto error con un code stabile, un message leggibile, il suo type e lo status HTTP, l’indicazione se è retryable, il request_id e un docs_url. Il request_id corrisponde sempre all’header di risposta X-Request-Id, quindi includilo quando contatti il supporto.

{
  "error": {
    "code": "INVALID_DOMAIN",
    "message": "Formato del dominio non valido",
    "suggestion": "Usa un dominio registrabile come example.com",
    "type": "validation_error",
    "status": 400,
    "retryable": false,
    "request_id": "m5x7k2p-a9f3",
    "docs_url": "https://domscan.net/docs/check-availability"
  }
}

Campi dell’errore

Codici di errore comuni

Questi sono i codici che la maggior parte dei client deve gestire. Alcuni endpoint restituiscono codici più specifici che seguono le stesse regole; l’elenco completo con stato, tipo e comportamento di nuovo tentativo è nella specifica OpenAPI sotto x-domscan-error-codes. RATE_LIMIT_EXCEEDED è ancora accettato come alias di RATE_LIMITED.

Come gestire i nuovi tentativi

• Riprova solo quando retryable è true. Per gli errori di validazione, autenticazione e autorizzazione, correggi prima la richiesta.
• Se è presente retry_after o l’header Retry-After, attendi almeno quel numero di secondi prima del tentativo successivo.
• In caso contrario usa un backoff esponenziale con jitter, ad esempio 1, 2, 4 e 8 secondi, e fermati dopo pochi tentativi.
• Per la creazione di batch e job, invia un header Idempotency-Key in modo che una richiesta ripetuta non crei mai un job duplicato.
• Per le altre richieste POST che addebitano crediti, un header Idempotency-Key fa sì che un nuovo tentativo restituisca la risposta memorizzata invece di addebitare di nuovo.

Compatibilità

Dal 10 ottobre 2026 ogni endpoint usa questo formato. I campi che alcuni endpoint già restituivano, come credits_remaining, purchase_url, login_url, success o meta, vengono mantenuti per un periodo di compatibilità, così le integrazioni esistenti continuano a funzionare. Nel nuovo codice leggi i dettagli dell’errore dall’oggetto error.