Errores de la API de Didit: códigos y soluciones

La API de Didit informa de un fallo con un código de estado HTTP y, casi siempre, con un cuerpo JSON. Esta página explica qué significa cada estado, qué forma tiene el cuerpo, qué valores de code puedes usar para tomar decisiones en tu lógica y qué fallos se pueden reintentar con seguridad. Básate primero en el estado y después en code cuando esté presente, porque el texto de un mensaje puede cambiar.

Códigos de estado

Estado	Qué significa	Qué hacer	¿Reintentar?
`400`	La solicitud no es válida: un campo no superó la validación o no se pudo leer una imagen o un documento	Corrige lo que indica el cuerpo	Después de corregirlo
`401`	La clave que enviaste es incorrecta, tiene un formato no válido, se revocó o expiró	Revisa `DIDIT_API_KEY` o crea una clave nueva	Después de corregirlo
`402`	No se pudo pagar la comprobación, así que no se ejecutó	Recarga tu saldo	Después de recargar
`403`	No se envió ninguna clave, la clave no tiene acceso a este recurso o acción, la solicitud llegó desde fuera de la lista de IP de la clave o el saldo no puede cubrir la solicitud	Lee el cuerpo y consulta Errores de clave de API y Créditos insuficientes	Después de corregirlo
`404`	El recurso no existe, o una sesión queda fuera de los flujos o estados de la clave	Revisa el id y los límites de la clave	No
`409`	La solicitud entra en conflicto con el estado actual, por ejemplo una `Idempotency-Key` reutilizada o un paso que ya se ejecutó	Lee `code` y vuelve a cargar el estado	Depende de `code`
`410`	El recurso expiró, por ejemplo una sesión o una invitación	Crea uno nuevo	No
`415`	El cuerpo de la solicitud no es JSON	Envía `Content-Type: application/json`	Después de corregirlo
`422`	Una dirección de wallet corresponde a más de una blockchain, así que no se analizó ni se facturó nada	Vuelve a enviarla con `blockchain` establecido en uno de los valores de `candidate_chains`	Después de corregirlo
`429`	Se alcanzó un límite de solicitudes o una cuota	Espera el tiempo indicado en `Retry-After`; consulta Límites de solicitudes	Sí, después de esperar
`500`	Se produjo un error inesperado del lado de Didit	Reintenta con backoff y contacta con soporte si persiste	Consulta Reintentos
`502`	Un servicio del que depende Didit devolvió un error	Lee `code`	Consulta Reintentos
`503`	Un servicio del que depende Didit no está disponible temporalmente	Lee `code` y vuelve a intentarlo	Consulta Reintentos

Cuerpos de error

Los cuerpos de error no comparten una misma estructura, así que léelos de forma defensiva. La forma depende de la familia de endpoints:

Forma	Dónde la ves	Ejemplo
`detail`	La mayoría de los errores, incluidos los de autenticación, recurso no encontrado y límites de solicitudes	`{"detail": "You do not have permission to perform this action."}`
`detail` y `code`	Errores con un código estable	`{"detail": "This application was deleted.", "code": "application_deleted"}`
Errores de campo	Validación de la entrada	`{"workflow_id": ["This field is required."]}`
`non_field_errors`	Validación entre varios campos	`{"non_field_errors": ["..."]}`
Un array JSON	Algunos errores de validación, como en una llamada de simulación	`["Scenario can only be armed before the verification starts."]`
`error`	La mayoría de las API independientes	`{"error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me"}`
`error` y `code`	Errores de imagen en las API independientes	`{"error": "...", "code": "invalid_image"}`
`error` como código, con `detail`	Verificación de wallets de identidad digital	`{"error": "insufficient_credits", "detail": "..."}`

Una respuesta 500 puede no tener ningún cuerpo JSON, así que gestiona los cuerpos que no se puedan analizar.

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

Errores de clave de API

Lo que enviaste	Estado	`detail`
Sin encabezado `x-api-key`	`403`	`You do not have permission to perform this action.`
Una clave incorrecta, con formato no válido o revocada	`401`	`Authentication credentials were not provided or are invalid.`
Una clave expirada	`401`	`This API key has expired.`
Una clave usada desde fuera de su lista de direcciones IP	`403`	`This API key can't be used from this IP address.`
Una clave con alcance limitado sin acceso a este recurso o acción	`403`	`This API key has no access to this endpoint.`
Una clave limitada a ciertos flujos o estados, en un endpoint que no puede usar	`403`	`This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint.`
Una clave limitada a ciertos flujos o estados, en una sesión fuera de esos límites	`404`	`Session not found.`
Una clave cuya aplicación se acaba de eliminar	`403`	`This application was deleted.`, con `"code": "application_deleted"`

Durante unos minutos después de eliminar una aplicación, la API responde con application_deleted y, a partir de entonces, rechaza la clave como cualquier clave incorrecta. No reintentes: la aplicación y sus claves ya no existen. Consulta Autenticación de la API y Claves de API para saber cómo funcionan las claves y sus límites.

Créditos insuficientes

Cada familia de API informa de un saldo insuficiente a su manera:

Llamada	Estado	Cuerpo
`POST /v3/session/`	`400`	`{"detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me"}`
La mayoría de las API independientes	`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ón de wallets de identidad digital	`403`	`{"error": "insufficient_credits", "detail": "..."}`
Transacciones, Travel Rule y validación de direcciones	`403`	`{"detail": "...", "code": "insufficient_credits"}`

Con un contrato, al crear una sesión, se recibe una respuesta 403 con "code": "contract_billing_suspended" cuando los servicios de pago están suspendidos para tu organización. Las aplicaciones de sandbox nunca se facturan, así que no pasan por estas comprobaciones.

Códigos de error

Estos valores de code son estables, así que puedes basar tu lógica en ellos. La mayoría aparecen junto a detail; en la verificación con wallets de Digital ID, el código es el valor de error.

Acceso y facturación

Código	Estado	Significado
`insufficient_credits`	`402`, `403`	El saldo no alcanza para cubrir la llamada
`contract_billing_suspended`	`403`	Los servicios de pago están en pausa para esta organización
`contract_rate_missing`	`402`, `403`	El contrato no tiene tarifa para esta comprobación
`application_deleted`	`403`	La aplicación de la clave se eliminó
`organization_deleted`	`403`	La organización de la clave se eliminó
`event_monitoring_disabled`	`403`	La ingesta de eventos no está activada para esta aplicación
`networks_not_entitled`	`403`	Las redes de fraude no están habilitadas para esta organización

Solicitudes e idempotencia

Código	Estado	Significado
`invalid_image`	`400`	No se pudo usar la imagen
`return_url_invalid`	`400`	La URL de retorno no está permitida
`idempotency_key_invalid`	`400`	La `Idempotency-Key` tiene más de 255 caracteres
`idempotency_key_reused`	`409`	La clave ya se usó con un cuerpo distinto
`idempotency_key_in_progress`	`409`	La primera solicitud con esta clave todavía se está procesando; espera lo que indique `Retry-After`
`verification_in_progress`	`409`	El usuario está completando esta verificación en este momento, así que no se puede cancelar; espera lo que indique `Retry-After`
`feature_override_not_pending`	`409`	La modificación ya se aplicó o se canceló

Comprobaciones bancarias, de teléfono y de riesgo

Código	Estado	Significado
`invalid_account_input`	`400`	Los datos de la cuenta no son válidos
`country_not_covered`	`404`	La comprobación no cubre este país o este tipo de cuenta
`bank_not_covered`	`404`	La comprobación no llega a este banco
`bank_verification_not_available`	`404`	Bank Verification todavía no está disponible
`account_check_unavailable`	`503`	La comprobación no está disponible temporalmente y la solicitud no se cobró
`phone_provider_unavailable`	`502`	La verificación de teléfono no está disponible temporalmente; no se factura nada y no se consume ningún intento
`risk_lookup_unavailable`	`502`	La consulta de riesgo no está disponible temporalmente y la solicitud no se cobró

Verificación de empresas (KYB)

Código	Estado	Significado
`kyb_registry_provider_unavailable`	`502`	El registro de empresas no está disponible temporalmente
`kyb_registry_country_unsupported`	`400`	La búsqueda en el registro no cubre este país
`kyb_registry_search_limit_reached`	`429`	La aplicación alcanzó su límite de 600 búsquedas de pago por hora
`kyb_session_not_writable`	`409`	La sesión ha finalizado
`kyb_step_mismatch`	`409`	La sesión está en otro paso; `next_step` indica cuál
`kyb_no_party_drafts`	`409`	No hay partes en borrador para enviar
`kyb_parties_already_submitted`	`409`	Las partes ya se enviaron
`kyb_party_kyc_session_not_deleted`	`409`	La verificación de la parte sigue activa, así que no se puede regenerar

Wallets de Digital ID

Código	Estado	Significado
`wallet_unavailable`	`403`	Esta wallet no está disponible para tu aplicación
`wallet_provider_unavailable`	`502`	No se pudo iniciar la wallet y no se creó nada
`wallet_not_configured`	`503`	Este entorno no puede conectarse con la wallet

Informes y casos

Código	Estado	Significado
`report_deletion_pending`	`409`	El informe se está eliminando; repite la eliminación para terminar de borrar sus archivos
`report_storage_unavailable`	`503`	No se pudieron borrar los archivos del informe; repite la eliminación
`wallet_address_deletion_incomplete`	`503`	No se pudo eliminar un archivo almacenado, así que la eliminación se detuvo; vuelve a intentarlo
`case_request_not_waiting`	`409`	La solicitud ya no está a la espera del cliente, así que no hay nada que recordarle
`case_request_reminder_too_soon`	`429`	Se envió un recordatorio hace poco; `retry_at` indica cuándo puedes enviar el siguiente

Firmas electrónicas

Código	Estado	Significado
`signature_not_found`	`404`	La firma no existe
`signature_field_not_found`	`404`	El campo de firma no existe
`signature_not_signed`	`404`, `409`	El documento no se ha firmado

Al crear una sesión, los problemas de documento siguientes llegan como valor del campo que presenta el problema, con estado 400, por ejemplo {"sign": "signature_document_changed"}:

Valor	Significado
`signature_document_changed`	El documento es distinto del que se envió primero
`signature_document_not_supported`	El formato del documento no es compatible
`signature_document_conversion_failed`	No se pudo convertir el documento
`field_anchor_not_found`	No se encontró en el documento el ancla de texto de un campo
`field_value_missing`	Un campo no tiene valor

Webhooks

Código	Estado	Significado
`webhook_url_missing`	`400`	La entrega no tiene ninguna URL registrada, así que no se envía nada
`invalid_webhook_payload`	`400`	Los datos del webhook no tienen un formato válido
`webhook_resend_error`	`400`	No se pudo volver a firmar la entrega almacenada o no se pudo completar el intento

Reintentos e idempotencia

Algunos errores se pueden repetir con seguridad y otros no:

429: espera lo que indica el encabezado Retry-After y luego reintenta.
502 y 503: reintenta con backoff cuando la referencia del endpoint indique que no se facturó nada, como ocurre con las comprobaciones de teléfono, correo electrónico, banco y riesgo.
502 en POST /v3/database-validation/: revisa primero cada entrada de validation_errors, porque este código de estado por sí solo no significa un error temporal.
503 en una eliminación: repite la misma solicitud hasta que devuelva 200.
Otros 4xx: corrige primero la solicitud, porque la misma solicitud falla de la misma forma.

POST /v3/aml/ y la verificación de wallet de Digital ID aceptan un encabezado Idempotency-Key de hasta 255 caracteres. Repetir una solicitud con la misma clave y el mismo cuerpo devuelve la respuesta almacenada, de modo que el procesamiento y el cargo se realizan una sola vez. Una solicitud con la misma clave y un cuerpo distinto devuelve 409 y, mientras la primera solicitud sigue en curso, los endpoints de wallets responden 409 con Retry-After. POST /v3/session/ no tiene clave de idempotencia, así que, si se agota el tiempo de espera al crear una sesión, consulta tus sesiones por vendor_data antes de crear otra.

Relacionado

Límite de solicitudes: límites, encabezados y el cuerpo de 429.
Autenticación de la API: cómo enviar tu clave de API.
Pruebas en sandbox: reproduce resultados sin datos reales ni facturación.
Webhooks: entrega, reintentos y orden.

Guías

Autenticación

Model Context Protocol (MCP)

SDKs web

SDKs nativos

SDK de servidor

Integraciones

Errores de la API de Didit: códigos y soluciones

Códigos de estado

Cuerpos de error

Errores de clave de API

Créditos insuficientes

Códigos de error

Acceso y facturación

Solicitudes e idempotencia

Comprobaciones bancarias, de teléfono y de riesgo

Verificación de empresas (KYB)

Wallets de Digital ID

Informes y casos

Firmas electrónicas

Webhooks

Reintentos e idempotencia

Relacionado

​Códigos de estado

​Cuerpos de error

​Errores de clave de API

​Créditos insuficientes

​Códigos de error

​Acceso y facturación

​Solicitudes e idempotencia

​Comprobaciones bancarias, de teléfono y de riesgo

​Verificación de empresas (KYB)

​Wallets de Digital ID

​Informes y casos

​Firmas electrónicas

​Webhooks

​Reintentos e idempotencia

​Relacionado

Códigos de estado

Cuerpos de error

Errores de clave de API

Créditos insuficientes

Códigos de error

Acceso y facturación

Solicitudes e idempotencia

Comprobaciones bancarias, de teléfono y de riesgo

Verificación de empresas (KYB)

Wallets de Digital ID

Informes y casos

Firmas electrónicas

Webhooks

Reintentos e idempotencia

Relacionado