> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Errori API Didit: codici di stato, risposte e soluzioni

> Tutti gli errori dell'API Didit: codici HTTP, corpo delle risposte, codici stabili e errori ritentabili. Include 401, 403, 409, 429 e 5xx.

The Didit API signala un errore con un codice di stato HTTP e, quasi sempre, con un corpo JSON.
Questa pagina elenca il significato di ogni stato, la struttura del corpo, i valori `code` su cui puoi basare la logica del tuo codice e gli errori che si possono ripetere in sicurezza.
Basati prima sullo stato e, quando è presente, su `code`, perché il testo di un messaggio può cambiare.

## Codici di stato

| Stato | Significato | Cosa fare | Riprova? |
| - | - | - | - |
| `400` | La richiesta non è valida: un campo non ha superato la validazione oppure un'immagine o un documento non può essere letto | Correggi ciò che il corpo indica | Dopo la correzione |
| `401` | La chiave che hai inviato è errata, malformata, revocata o scaduta | Controlla `DIDIT_API_KEY` oppure crea una nuova chiave | Dopo la correzione |
| `402` | La verifica non può essere pagata, quindi non è stata eseguita | Ricarica il tuo saldo | Dopo la ricarica |
| `403` | Non è stata inviata alcuna chiave, la chiave non ha accesso a questa risorsa o azione, la richiesta proviene da un indirizzo IP al di fuori dell'elenco di indirizzi IP della chiave oppure il saldo non copre la chiamata | Leggi il corpo, poi consulta [Errori delle chiavi API](#errori-delle-chiavi-api) e [Crediti insufficienti](#crediti-insufficienti) | Dopo la correzione |
| `404` | La risorsa non esiste, oppure una sessione è al di fuori dei workflow o degli stati consentiti alla chiave | Controlla l'id e i limiti della chiave | No |
| `409` | La richiesta è in conflitto con lo stato attuale, per esempio un `Idempotency-Key` riutilizzato o un passaggio già eseguito | Leggi `code` e ricarica lo stato | Dipende da `code` |
| `410` | La risorsa è scaduta, per esempio una sessione o un invito | Creane una nuova | No |
| `415` | Il corpo della richiesta non è JSON | Invia `Content-Type: application/json` | Dopo la correzione |
| `422` | Un indirizzo corrisponde a più di una blockchain, quindi non è stato eseguito alcuno screening né alcun addebito | Reinvia con `blockchain` impostato a uno dei valori di `candidate_chains` | Dopo la correzione |
| `429` | È stato raggiunto un limite di frequenza o una quota | Attendi `Retry-After`; vedi [Limiti di frequenza](https://docs.didit.me/it/integration/rate-limiting.md) | Sì, dopo l'attesa |
| `500` | Un errore imprevisto da parte di Didit | Riprova con backoff e contatta il supporto se il problema persiste | Vedi [Nuovi tentativi](#nuovi-tentativi-e-idempotenza) |
| `502` | Un servizio da cui dipende Didit ha restituito un errore | Leggi `code` | Vedi [Nuovi tentativi](#nuovi-tentativi-e-idempotenza) |
| `503` | Un servizio da cui dipende Didit è temporaneamente non disponibile | Leggi `code` e riprova | Vedi [Nuovi tentativi](#nuovi-tentativi-e-idempotenza) |

## Corpi degli errori

I corpi di errore non hanno un formato unico, quindi leggili in modo difensivo.
Il formato dipende dalla famiglia di endpoint:

| Formato | Dove lo vedi | Esempio |
| - | - | - |
| `detail` | La maggior parte degli errori, inclusi autenticazione, risorsa non trovata e limiti di frequenza | `{"detail": "You do not have permission to perform this action."}` |
| `detail` e `code` | Errori con un codice stabile | `{"detail": "This application was deleted.", "code": "application_deleted"}` |
| Errori di campo | Validazione dell'input | `{"workflow_id": ["This field is required."]}` |
| `non_field_errors` | Validazione tra più campi | `{"non_field_errors": ["..."]}` |
| Un array JSON | Alcuni errori di validazione, come una chiamata di simulazione | `["Scenario can only be armed before the verification starts."]` |
| `error` | La maggior parte delle API autonome | `{"error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me"}` |
| `error` e `code` | Errori sulle immagini nelle API autonome | `{"error": "...", "code": "invalid_image"}` |
| `error` come codice, con `detail` | Verifica tramite wallet di identità digitale | `{"error": "insufficient_credits", "detail": "..."}` |

Un `500` potrebbe non avere affatto un corpo JSON, quindi gestisci anche un corpo che non può essere interpretato.

```javascript theme={null}
const raw = await response.text();
let body = {};
try {
  body = JSON.parse(raw);
} catch {
  // A 5xx response may not be JSON: rely on response.status.
}
const code = body.code ?? null;
const message = body.detail ?? body.error ?? (Array.isArray(body) ? body[0] : raw);
```

## Errori delle chiavi API

| Cosa hai inviato | Stato | `detail` |
| - | - | - |
| Nessun header `x-api-key` | `403` | `You do not have permission to perform this action.` |
| Una chiave errata, malformata o revocata | `401` | `Authentication credentials were not provided or are invalid.` |
| Una chiave scaduta | `401` | `This API key has expired.` |
| Una chiave utilizzata da un indirizzo IP al di fuori del relativo elenco di indirizzi IP | `403` | `This API key can't be used from this IP address.` |
| Una chiave con ambito limitato senza accesso a questa risorsa o azione | `403` | `This API key has no access to this endpoint.` |
| Una chiave limitata a determinati workflow o stati, su un endpoint che non può usare | `403` | `This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint.` |
| Una chiave limitata a determinati workflow o stati, su una sessione fuori da tali limiti | `404` | `Session not found.` |
| Una chiave la cui applicazione è stata appena eliminata | `403` | `This application was deleted.`, con `"code": "application_deleted"` |

Per alcuni minuti dopo l'eliminazione di un'applicazione, l'API risponde con `application_deleted`; dopo di che rifiuta la chiave come qualsiasi chiave errata.
Non riprovare: l'applicazione e le sue chiavi sono state eliminate.

Consulta [Autenticazione API](https://docs.didit.me/it/getting-started/api-authentication.md) e [Chiavi API](https://docs.didit.me/it/console/api-keys.md) per capire come funzionano le chiavi e i relativi limiti.

## Crediti insufficienti

Ogni famiglia di API segnala un saldo basso in modo diverso:

| Chiamata | Stato | Corpo |
| - | - | - |
| `POST /v3/session/` | `400` | `{"detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me"}` |
| La maggior parte delle API autonome | `403` | `{"error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me"}` |
| `POST /v3/bank/account-check/` | `402` | `{"detail": "...", "code": "insufficient_credits"}` |
| Verifica tramite wallet di identità digitale | `403` | `{"error": "insufficient_credits", "detail": "..."}` |
| Transazioni, Travel Rule e validazione degli indirizzi | `403` | `{"detail": "...", "code": "insufficient_credits"}` |

Con un contratto, la creazione di una sessione risponde con `403` e `"code": "contract_billing_suspended"` mentre i servizi a pagamento sono sospesi per la tua organizzazione.
Le [applicazioni sandbox](https://docs.didit.me/it/integration/sandbox-testing.md) non vengono mai addebitate, quindi non sono soggette a questi controlli.

## Codici di errore

Questi valori `code` sono stabili, quindi puoi basarti su di essi per gestire i casi. La maggior parte si trova accanto a `detail`; nella verifica con wallet di identità digitale il codice è il valore di `error`.

### Accesso e fatturazione

| Codice | Stato | Significato |
| - | - | - |
| `insufficient_credits` | `402`, `403` | Il saldo non copre la chiamata |
| `contract_billing_suspended` | `403` | I servizi a pagamento sono sospesi per questa organizzazione |
| `contract_rate_missing` | `402`, `403` | Il contratto non prevede una tariffa per questo controllo |
| `application_deleted` | `403` | L'applicazione a cui appartiene la chiave è stata eliminata |
| `organization_deleted` | `403` | L'organizzazione a cui appartiene la chiave è stata eliminata |
| `event_monitoring_disabled` | `403` | L'acquisizione degli eventi non è attiva per questa applicazione |
| `networks_not_entitled` | `403` | Le reti antifrode non sono abilitate per questa organizzazione |

### Richieste e idempotenza

| Codice | Stato | Significato |
| - | - | - |
| `invalid_image` | `400` | Non è stato possibile utilizzare l'immagine |
| `return_url_invalid` | `400` | L'URL di ritorno non è consentito |
| `idempotency_key_invalid` | `400` | L'`Idempotency-Key` supera i 255 caratteri |
| `idempotency_key_reused` | `409` | La chiave era già stata usata con un corpo diverso |
| `idempotency_key_in_progress` | `409` | La prima richiesta con questa chiave è ancora in esecuzione; attendi `Retry-After` |
| `verification_in_progress` | `409` | L'utente sta completando questa verifica in questo momento, quindi non può essere annullata; attendi `Retry-After` |
| `feature_override_not_pending` | `409` | La sostituzione è già stata applicata o annullata |

### Controlli bancari, telefonici e di rischio

| Codice | Stato | Significato |
| - | - | - |
| `invalid_account_input` | `400` | I dati del conto non sono validi |
| `country_not_covered` | `404` | Il controllo non copre questo paese o questo tipo di conto |
| `bank_not_covered` | `404` | Il controllo non raggiunge questa banca |
| `bank_verification_not_available` | `404` | La verifica bancaria non è disponibile |
| `account_check_unavailable` | `503` | Il controllo è temporaneamente non disponibile e la richiesta non è stata addebitata |
| `phone_provider_unavailable` | `502` | La verifica telefonica è temporaneamente non disponibile; non viene addebitato nulla e non viene consumato alcun tentativo |
| `risk_lookup_unavailable` | `502` | La ricerca del rischio è temporaneamente non disponibile e la richiesta non è stata addebitata |

### Verifica aziendale (KYB)

| Codice | Stato | Significato |
| - | - | - |
| `kyb_registry_provider_unavailable` | `502` | Il registro delle imprese è temporaneamente non disponibile |
| `kyb_registry_country_unsupported` | `400` | La ricerca nel registro non copre questo paese |
| `kyb_registry_search_limit_reached` | `429` | L'applicazione ha raggiunto il limite di 600 ricerche a pagamento all'ora |
| `kyb_session_not_writable` | `409` | La sessione è conclusa |
| `kyb_step_mismatch` | `409` | La sessione si trova su un altro passaggio; `next_step` lo indica |
| `kyb_no_party_drafts` | `409` | Non ci sono bozze di soggetti da inviare |
| `kyb_parties_already_submitted` | `409` | I soggetti sono già stati inviati |
| `kyb_party_kyc_session_not_deleted` | `409` | La verifica del soggetto è ancora attiva, quindi non può essere rigenerata |

### Wallet di identità digitale

| Codice | Stato | Significato |
| - | - | - |
| `wallet_unavailable` | `403` | Questo wallet non è disponibile per la tua applicazione |
| `wallet_provider_unavailable` | `502` | Il wallet non è riuscito ad avviarsi e non è stato creato nulla |
| `wallet_not_configured` | `503` | Questo ambiente non può raggiungere il wallet |

### Report e casi

| Codice | Stato | Significato |
| - | - | - |
| `report_deletion_pending` | `409` | Il report è in fase di eliminazione; ripeti l'eliminazione per completare la cancellazione dei suoi file |
| `report_storage_unavailable` | `503` | Non è stato possibile cancellare i file del report; ripeti l'eliminazione |
| `wallet_address_deletion_incomplete` | `503` | Non è stato possibile eliminare un file memorizzato, quindi l'eliminazione si è interrotta; riprova |
| `case_request_not_waiting` | `409` | La richiesta non è più in attesa del cliente, quindi non c'è nulla da ricordargli |
| `case_request_reminder_too_soon` | `429` | Un promemoria è stato inviato di recente; `retry_at` indica quando potrai inviarne un altro |

### Firme elettroniche

| Codice | Stato | Significato |
| - | - | - |
| `signature_not_found` | `404` | La firma non esiste |
| `signature_field_not_found` | `404` | Il campo della firma non esiste |
| `signature_not_signed` | `404`, `409` | Il documento non è stato firmato |

Alla creazione della sessione, i problemi relativi al documento descritti di seguito vengono restituiti come valore del campo interessato con stato `400`, ad esempio `{"sign": "signature_document_changed"}`:

| Valore | Significato |
| - | - |
| `signature_document_changed` | Il documento è diverso da quello inviato per primo |
| `signature_document_not_supported` | Il formato del documento non è supportato |
| `signature_document_conversion_failed` | Non è stato possibile convertire il documento |
| `field_anchor_not_found` | Il testo di riferimento di un campo non è stato trovato nel documento |
| `field_value_missing` | Un campo non ha un valore |

### Webhook

| Codice | Stato | Significato |
| - | - | - |
| `webhook_url_missing` | `400` | La consegna non ha un URL registrato, quindi non viene inviato nulla |
| `invalid_webhook_payload` | `400` | I dati del webhook non sono in un formato valido |
| `webhook_resend_error` | `400` | Non è stato possibile firmare nuovamente la consegna memorizzata, oppure il tentativo non è stato completato |

## Nuovi tentativi e idempotenza

Alcuni errori possono essere ripetuti in sicurezza, altri no:

* **`429`:** attendi il valore dell'intestazione `Retry-After`, poi riprova.
* **`502` e `503`:** riprova con backoff quando il riferimento dell'endpoint indica che non è stato addebitato nulla, come avviene per i controlli telefonici, email, bancari e di rischio.
* **`502` su `POST /v3/database-validation/`:** leggi prima ogni voce di `validation_errors`, perché questo stato da solo non indica un errore temporaneo.
* **`503` su una cancellazione:** ripeti la stessa richiesta finché non restituisce `200`.
* **Altri `4xx`:** correggi prima la richiesta, perché la stessa richiesta fallisce allo stesso modo.

`POST /v3/aml/` e la verifica del wallet Digital ID accettano un'intestazione `Idempotency-Key` di massimo 255 caratteri.
Ripetere una richiesta con la stessa chiave e lo stesso corpo restituisce la risposta memorizzata, quindi l'operazione viene eseguita e l'addebito viene effettuato una sola volta.
La stessa chiave con un corpo diverso restituisce `409`, e mentre la prima richiesta è ancora in esecuzione gli endpoint del wallet rispondono `409` con `Retry-After`.

`POST /v3/session/` non ha una chiave di idempotenza, quindi se la creazione va in timeout, elenca le tue sessioni per `vendor_data` prima di crearne un'altra.

## Correlati

* [Limiti di frequenza](https://docs.didit.me/it/integration/rate-limiting.md): limiti, intestazioni e corpo della risposta `429`.
* [Autenticazione API](https://docs.didit.me/it/getting-started/api-authentication.md): come inviare la tua chiave.
* [Test in sandbox](https://docs.didit.me/it/integration/sandbox-testing.md): riproduci gli esiti senza dati reali né addebiti.
* [Webhook](https://docs.didit.me/it/integration/webhooks.md): consegna, nuovi tentativi e ordine.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.