Errors de l'API de Didit: codis, cossos i solucions

L’API de Didit indica un error amb un codi d’estat HTTP i, en gairebé tots els casos, amb un cos en JSON. Aquesta pàgina enumera el significat de cada estat, l’aspecte del cos, els valors de code pels quals pots decidir una acció i els errors que es poden reintentar sense risc. Fia’t primer de l’estat i, si hi és, de code, perquè el text d’un missatge pot canviar.

Codis d’estat

Codi HTTP	Què significa	Què has de fer	Reintentar?
`400`	La sol·licitud no és vàlida: un camp no ha superat la validació, o no s’ha pogut llegir una imatge o un document	Corregeix el que indica el cos	Després de corregir-ho
`401`	La clau que has enviat és incorrecta, mal formada, revocada o caducada	Revisa `DIDIT_API_KEY` o crea una clau nova	Després de corregir-ho
`402`	No s’ha pogut cobrar la comprovació, per això no s’ha executat	Recarrega el saldo	Després de recarregar
`403`	No s’ha enviat cap clau, la clau no té accés a aquest recurs o acció, la sol·licitud arriba des de fora de la llista d’adreces IP de la clau, o el saldo no cobreix la crida	Llegeix el cos i consulta Errors de clau d’API i Crèdits insuficients	Després de corregir-ho
`404`	El recurs no existeix, o una sessió queda fora dels fluxos o estats de la clau	Revisa l’identificador i els límits de la clau	No
`409`	La sol·licitud entra en conflicte amb l’estat actual, per exemple un `Idempotency-Key` reutilitzat o un pas que ja s’ha executat	Llegeix `code` i torna a carregar l’estat	Depèn de `code`
`410`	El recurs ha caducat, per exemple una sessió o una invitació	Crea’n un de nou	No
`415`	El cos de la sol·licitud no és JSON	Envia `Content-Type: application/json`	Després de corregir-ho
`422`	Una adreça de cartera encaixa amb més d’una blockchain, per això no s’ha fet cap cribratge ni s’ha facturat res	Torna a enviar-la amb `blockchain` definit com un dels valors de `candidate_chains`	Després de corregir-ho
`429`	S’ha assolit un límit de freqüència o una quota	Espera el temps indicat per `Retry-After`; consulta Límit de freqüència	Sí, després d’esperar
`500`	Un error inesperat per part de Didit	Reintenta amb retard progressiu i contacta amb suport si continua	Consulta Reintents
`502`	Un servei del qual depèn Didit ha retornat un error	Llegeix `code`	Consulta Reintents
`503`	Un servei del qual depèn Didit no està disponible temporalment	Llegeix `code` i torna-ho a intentar	Consulta Reintents

Cossos d’error

Els cossos d’error no comparteixen un mateix format, així que llegeix-los de manera defensiva. La forma depèn de la família d’endpoints:

Forma	On la veus	Exemple
`detail`	La majoria d’errors, inclosa l’autenticació, la indicació que no s’ha trobat el recurs i els límits de freqüència	`{"detail": "You do not have permission to perform this action."}`
`detail` i `code`	Errors amb un codi estable	`{"detail": "This application was deleted.", "code": "application_deleted"}`
Errors de camp	Validació d’entrada	`{"workflow_id": ["This field is required."]}`
`non_field_errors`	Validació entre diversos camps	`{"non_field_errors": ["..."]}`
Un array JSON	Alguns errors de validació, com una crida de simulació	`["Scenario can only be armed before the verification starts."]`
`error`	La majoria d’APIs independents	`{"error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me"}`
`error` i `code`	Errors d’imatge en APIs independents	`{"error": "...", "code": "invalid_image"}`
`error` com a codi, amb `detail`	Verificació amb cartera d’identitat digital	`{"error": "insufficient_credits", "detail": "..."}`

Un 500 pot no tenir cap cos JSON, així que gestiona un cos que no es pot analitzar.

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);

Errors de clau d’API

Què has enviat	Estat	`detail`
Cap capçalera `x-api-key`	`403`	`You do not have permission to perform this action.`
Una clau incorrecta, mal formada o revocada	`401`	`Authentication credentials were not provided or are invalid.`
Una clau caducada	`401`	`This API key has expired.`
Una clau utilitzada des de fora de la seva llista d’adreces IP	`403`	`This API key can't be used from this IP address.`
Una clau amb permisos limitats i sense accés a aquest recurs o acció	`403`	`This API key has no access to this endpoint.`
Una clau limitada a alguns fluxos o estats, en un endpoint que no pot utilitzar	`403`	`This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint.`
Una clau limitada a alguns fluxos o estats, en una sessió fora d’aquests límits	`404`	`Session not found.`
Una clau l’aplicació de la qual s’acaba d’eliminar	`403`	`This application was deleted.`, amb `"code": "application_deleted"`

Durant uns minuts després d’eliminar una aplicació, l’API respon amb application_deleted, i després rebutja la clau com qualsevol clau incorrecta. No reintentis: l’aplicació i les seves claus ja no existeixen. Consulta Autenticació de l’API i Claus d’API per saber com funcionen les claus i els seus límits.

Crèdits insuficients

Cada família d’APIs informa d’un saldo baix de manera diferent:

Crida	Estat	Cos
`POST /v3/session/`	`400`	`{"detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me"}`
La majoria d’APIs independents	`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"}`
Verificació amb cartera d’identitat digital	`403`	`{"error": "insufficient_credits", "detail": "..."}`
Transaccions, Travel Rule i validació d’adreces	`403`	`{"detail": "...", "code": "insufficient_credits"}`

En un contracte, la creació de sessió respon amb 403 i "code": "contract_billing_suspended" mentre els serveis de pagament estiguin suspesos per a la teva organització. Les aplicacions de sandbox mai es facturen, així que no fan aquestes comprovacions.

Codis d’error

Aquests valors de code són estables, així que pots basar-hi la lògica del codi. La majoria apareixen al costat de detail; a la verificació amb carteres d’identitat digital, el codi és el valor de error.

Accés i facturació

Codi	Estat	Significat
`insufficient_credits`	`402`, `403`	El saldo no cobreix la crida
`contract_billing_suspended`	`403`	Els serveis de pagament estan pausats per a aquesta organització
`contract_rate_missing`	`402`, `403`	El contracte no té tarifa per a aquesta comprovació
`application_deleted`	`403`	L’aplicació de la clau s’ha eliminat
`organization_deleted`	`403`	L’organització de la clau s’ha eliminat
`event_monitoring_disabled`	`403`	La ingestió d’esdeveniments no està activada per a aquesta aplicació
`networks_not_entitled`	`403`	Les xarxes de frau no estan habilitades per a aquesta organització

Sol·licituds i idempotència

Codi	Estat	Significat
`invalid_image`	`400`	No s’ha pogut utilitzar la imatge
`return_url_invalid`	`400`	La URL de retorn no està permesa
`idempotency_key_invalid`	`400`	La `Idempotency-Key` té més de 255 caràcters
`idempotency_key_reused`	`409`	La clau ja s’ha utilitzat amb un cos diferent
`idempotency_key_in_progress`	`409`	La primera sol·licitud amb aquesta clau encara s’està executant; espera el valor de `Retry-After`
`verification_in_progress`	`409`	L’usuari està completant aquesta verificació en aquest moment, així que no es pot cancel·lar; espera el valor de `Retry-After`
`feature_override_not_pending`	`409`	La modificació ja s’ha aplicat o s’ha cancel·lat

Comprovacions bancàries, de telèfon i de risc

Codi	Estat	Significat
`invalid_account_input`	`400`	Les dades del compte no són vàlides
`country_not_covered`	`404`	La comprovació no cobreix aquest país ni aquest tipus de compte
`bank_not_covered`	`404`	La comprovació no arriba a aquest banc
`bank_verification_not_available`	`404`	La verificació bancària no està disponible
`account_check_unavailable`	`503`	La comprovació no està disponible temporalment i la sol·licitud no s’ha cobrat
`phone_provider_unavailable`	`502`	La verificació de telèfon no està disponible temporalment; no es factura res i no es consumeix cap intent
`risk_lookup_unavailable`	`502`	La consulta de risc no està disponible temporalment i la sol·licitud no s’ha cobrat

Verificació d’empreses (KYB)

Codi	Estat	Significat
`kyb_registry_provider_unavailable`	`502`	El registre mercantil no està disponible temporalment
`kyb_registry_country_unsupported`	`400`	La cerca al registre no cobreix aquest país
`kyb_registry_search_limit_reached`	`429`	L’aplicació ha arribat al límit de 600 cerques de pagament per hora
`kyb_session_not_writable`	`409`	La sessió ha finalitzat
`kyb_step_mismatch`	`409`	La sessió es troba en un altre pas; `next_step` n’indica quin
`kyb_no_party_drafts`	`409`	No hi ha esborranys de parts per enviar
`kyb_parties_already_submitted`	`409`	Les parts ja s’han enviat
`kyb_party_kyc_session_not_deleted`	`409`	La verificació de la part encara està activa, així que no es pot regenerar

Carteres d’identitat digital

Codi	Estat	Significat
`wallet_unavailable`	`403`	Aquesta cartera no està disponible per a la teva aplicació
`wallet_provider_unavailable`	`502`	La cartera no s’ha pogut iniciar i no s’ha creat res
`wallet_not_configured`	`503`	Aquest entorn no pot accedir a la cartera

Informes i casos

Codi	Estat	Significat
`report_deletion_pending`	`409`	L’informe s’està eliminant; repeteix l’eliminació per acabar d’esborrar els seus fitxers
`report_storage_unavailable`	`503`	No s’han pogut esborrar els fitxers de l’informe; repeteix l’eliminació
`wallet_address_deletion_incomplete`	`503`	No s’ha pogut eliminar un fitxer emmagatzemat, així que l’eliminació s’ha aturat; torna-ho a provar
`case_request_not_waiting`	`409`	La sol·licitud ja no està pendent del client, així que no hi ha res a recordar-li
`case_request_reminder_too_soon`	`429`	Fa poc que s’ha enviat un recordatori; `retry_at` indica quan pots enviar el següent

Signatures electròniques

Codi	Estat	Significat
`signature_not_found`	`404`	La signatura no existeix
`signature_field_not_found`	`404`	El camp de signatura no existeix
`signature_not_signed`	`404`, `409`	El document no s’ha signat

En crear la sessió, els problemes del document següents arriben com a valor del camp que els origina, amb estat 400, per exemple {"sign": "signature_document_changed"}:

Valor	Significat
`signature_document_changed`	El document és diferent del que es va enviar primer
`signature_document_not_supported`	El format del document no és compatible
`signature_document_conversion_failed`	No s’ha pogut convertir el document
`field_anchor_not_found`	No s’ha trobat l’ancoratge de text del camp al document
`field_value_missing`	Un camp no té valor

Webhooks

Codi	Estat	Significat
`webhook_url_missing`	`400`	El lliurament no té cap URL registrada, així que no s’envia res
`invalid_webhook_payload`	`400`	Les dades del webhook no tenen un format vàlid
`webhook_resend_error`	`400`	El lliurament emmagatzemat no s’ha pogut tornar a signar, o no s’ha pogut completar l’intent

Reintents i idempotència

Alguns errors es poden repetir amb seguretat i d’altres no:

429: espera la capçalera Retry-After i, després, torna-ho a intentar.
502 i 503: torna-ho a intentar amb retrocés quan la referència de l’endpoint indiqui que no s’ha facturat res, com passa amb les comprovacions de telèfon, correu electrònic, bancàries i de risc.
502 en POST /v3/database-validation/: llegeix primer cada entrada de validation_errors, perquè aquest estat per si sol no significa un error temporal.
503 en una eliminació: repeteix la mateixa sol·licitud fins que retorni 200.
Altres 4xx: corregeix primer la sol·licitud, perquè la mateixa sol·licitud fallarà de la mateixa manera.

POST /v3/aml/ i la verificació de cartera de Digital ID accepten una capçalera Idempotency-Key de fins a 255 caràcters. Si repeteixes una sol·licitud amb la mateixa clau i el mateix cos, es reprodueix la resposta emmagatzemada, de manera que l’operació i el càrrec s’executen una sola vegada. La mateixa clau amb un cos diferent respon amb 409, i mentre la primera sol·licitud encara s’està executant, els endpoints de cartera responen amb 409 i Retry-After. POST /v3/session/ no té cap clau d’idempotència, així que, si una creació supera el temps d’espera, llista les sessions per vendor_data abans de crear-ne una altra.

Relacionat

Límit de freqüència: límits, capçaleres i el cos de la resposta 429.
Autenticació de l’API: com enviar la teva clau.
Proves al sandbox: reprodueix els resultats sense dades reals ni facturació.
Webhooks: lliurament, reintents i ordre.

Guies

Autenticació

Model Context Protocol (MCP)

SDK web

SDK natius

SDK de servidor

Integracions

Errors de l'API de Didit: codis, cossos i solucions

Codis d’estat

Cossos d’error

Errors de clau d’API

Crèdits insuficients

Codis d’error

Accés i facturació

Sol·licituds i idempotència

Comprovacions bancàries, de telèfon i de risc

Verificació d’empreses (KYB)

Carteres d’identitat digital

Informes i casos

Signatures electròniques

Webhooks

Reintents i idempotència

Relacionat

​Codis d’estat

​Cossos d’error

​Errors de clau d’API

​Crèdits insuficients

​Codis d’error

​Accés i facturació

​Sol·licituds i idempotència

​Comprovacions bancàries, de telèfon i de risc

​Verificació d’empreses (KYB)

​Carteres d’identitat digital

​Informes i casos

​Signatures electròniques

​Webhooks

​Reintents i idempotència

​Relacionat

Codis d’estat

Cossos d’error

Errors de clau d’API

Crèdits insuficients

Codis d’error

Accés i facturació

Sol·licituds i idempotència

Comprovacions bancàries, de telèfon i de risc

Verificació d’empreses (KYB)

Carteres d’identitat digital

Informes i casos

Signatures electròniques

Webhooks

Reintents i idempotència

Relacionat