Errori API Didit: codici di stato, risposte e soluzioni

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 e 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	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
`502`	Un servizio da cui dipende Didit ha restituito un errore	Leggi `code`	Vedi Nuovi tentativi
`503`	Un servizio da cui dipende Didit è temporaneamente non disponibile	Leggi `code` e riprova	Vedi Nuovi tentativi

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.

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 e Chiavi API 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 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: limiti, intestazioni e corpo della risposta 429.
Autenticazione API: come inviare la tua chiave.
Test in sandbox: riproduci gli esiti senza dati reali né addebiti.
Webhook: consegna, nuovi tentativi e ordine.

Guide

Autenticazione

Model Context Protocol (MCP)

SDK web

SDK nativi

SDK server

Integrazioni

Errori API Didit: codici di stato, risposte e soluzioni

Codici di stato

Corpi degli errori

Errori delle chiavi API

Crediti insufficienti

Codici di errore

Accesso e fatturazione

Richieste e idempotenza

Controlli bancari, telefonici e di rischio

Verifica aziendale (KYB)

Wallet di identità digitale

Report e casi

Firme elettroniche

Webhook

Nuovi tentativi e idempotenza

Correlati

​Codici di stato

​Corpi degli errori

​Errori delle chiavi API

​Crediti insufficienti

​Codici di errore

​Accesso e fatturazione

​Richieste e idempotenza

​Controlli bancari, telefonici e di rischio

​Verifica aziendale (KYB)

​Wallet di identità digitale

​Report e casi

​Firme elettroniche

​Webhook

​Nuovi tentativi e idempotenza

​Correlati

Codici di stato

Corpi degli errori

Errori delle chiavi API

Crediti insufficienti

Codici di errore

Accesso e fatturazione

Richieste e idempotenza

Controlli bancari, telefonici e di rischio

Verifica aziendale (KYB)

Wallet di identità digitale

Report e casi

Firme elettroniche

Webhook

Nuovi tentativi e idempotenza

Correlati