> For the complete documentation index see https://domscan.net/llms.txt. Markdown versions of every docs page are available by appending .md to the page URL.

Source: https://domscan.net/it/docs/error-codes

# Codici di errore

Consulta la documentazione API di Codici di errore, i parametri delle richieste, i campi delle risposte, gli esempi di codice e la gestione degli errori per le integrazioni DomScan.

### 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.

```json
{
  "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

| Campo | Descrizione |
| --- | --- |
| `code` | Codice di errore stabile e leggibile da una macchina. I codici non vengono mai rinominati, quindi puoi usarli in tutta sicurezza per gestire i diversi casi. |
| `message` | Spiegazione leggibile dell’errore. La formulazione può cambiare, quindi non analizzarla nel codice. |
| `type` | Categoria generale dell’errore, ad esempio `validation_error`, `authentication_error` o `rate_limit_error`. |
| `status` | Il codice di stato HTTP, ripetuto nel corpo per log e code di messaggi. |
| `retryable` | Indica se la stessa richiesta può riuscire se la ripeti più tardi. |
| `request_id` | Identificatore univoco della richiesta. Corrisponde all’header `X-Request-Id`. |
| `docs_url` | Link alla sezione della documentazione che spiega questo errore. |
| `suggestion` | Suggerimento facoltativo su come correggere la richiesta. |
| `details` | Contesto strutturato facoltativo, ad esempio i metodi consentiti o il parametro non valido. |
| `retry_after` | Numero facoltativo di secondi da attendere prima di riprovare. Viene inviato anche come header `Retry-After`. |

### 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`.

| Codice | Stato HTTP | Tipo | Riproponibile | Descrizione |
| --- | --- | --- | --- | --- |
| `BAD_REQUEST` | 400 | `validation_error` | No | Parametri mancanti o non validi |
| `MISSING_PARAMETER` | 400 | `validation_error` | No | Manca un parametro obbligatorio |
| `INVALID_PARAMETER` | 400 | `validation_error` | No | Un parametro ha un valore non valido |
| `INVALID_JSON` | 400 | `validation_error` | No | Il corpo della richiesta non è un JSON valido |
| `INVALID_DOMAIN` | 400 | `validation_error` | No | Formato dominio non valido |
| `UNSUPPORTED_TLD` | 400 | `validation_error` | No | TLD non supportato |
| `SUBDOMAIN_NOT_SUPPORTED` | 400 | `validation_error` | No | Questo endpoint accetta domini registrabili, non sottodomini |
| `VALIDATION_ERROR` | 422 | `validation_error` | No | La richiesta è formalmente corretta ma non può essere elaborata |
| `AUTH_REQUIRED` | 401 | `authentication_error` | No | Non è stata fornita alcuna chiave API né sessione |
| `INVALID_API_KEY` | 401 | `authentication_error` | No | La chiave API non è valida o è stata revocata |
| `INSUFFICIENT_CREDITS` | 402 | `credits_error` | No | Il tuo account non ha crediti sufficienti per questa richiesta |
| `FORBIDDEN` | 403 | `permission_error` | No | Non hai l’autorizzazione per questa azione |
| `NOT_FOUND` | 404 | `not_found_error` | No | L’endpoint o la risorsa non esiste |
| `METHOD_NOT_ALLOWED` | 405 | `request_error` | No | L’endpoint esiste ma non accetta questo metodo HTTP. L’header `Allow` elenca i metodi supportati. |
| `CONFLICT` | 409 | `conflict_error` | No | La richiesta è in conflitto con lo stato attuale della risorsa |
| `IDEMPOTENCY_CONFLICT` | 409 | `conflict_error` | No | La chiave di idempotenza è già stata usata con una richiesta diversa |
| `IDEMPOTENCY_KEY_REUSED` | 422 | `validation_error` | No | Questa `Idempotency-Key` è già stata usata con una richiesta diversa nelle ultime 24 ore. Usa una nuova chiave per una nuova richiesta. |
| `IDEMPOTENCY_IN_PROGRESS` | 409 | `conflict_error` | Sì | Una richiesta con questa `Idempotency-Key` è ancora in corso. Riprova tra un momento per ricevere la risposta memorizzata. |
| `RATE_LIMITED` | 429 | `rate_limit_error` | Sì | Troppe richieste |
| `INTERNAL` | 500 | `api_error` | No | Errore imprevisto del server. Se persiste, contatta il supporto indicando l’ID della richiesta. |
| `UPSTREAM_ERROR` | 502 | `upstream_error` | Sì | Una fonte a monte ha restituito una risposta non utilizzabile |
| `UPSTREAM_UNAVAILABLE` | 503 | `upstream_error` | Sì | Una fonte a monte è temporaneamente non disponibile |
| `SERVICE_UNAVAILABLE` | 503 | `upstream_error` | Sì | Il servizio è temporaneamente non disponibile |
| `TIMEOUT` | 504 | `timeout_error` | Sì | Una fonte a monte o un registro non ha risposto in tempo |

### 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`.