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

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

> Todos los errores de la API de Didit: códigos HTTP, formato de respuesta, códigos de error estables y qué fallos reintentar. Incluye 401, 403, 409, 429 y 5xx.

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](#errores-de-clave-de-api) y [Créditos insuficientes](#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](https://docs.didit.me/es/integration/rate-limiting.md) | 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](#reintentos-e-idempotencia) |
| `502` | Un servicio del que depende Didit devolvió un error | Lee `code` | Consulta [Reintentos](#reintentos-e-idempotencia) |
| `503` | Un servicio del que depende Didit no está disponible temporalmente | Lee `code` y vuelve a intentarlo | Consulta [Reintentos](#reintentos-e-idempotencia) |

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

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

## 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](https://docs.didit.me/es/getting-started/api-authentication.md) y [Claves de API](https://docs.didit.me/es/console/api-keys.md) 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](https://docs.didit.me/es/integration/sandbox-testing.md) 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](https://docs.didit.me/es/integration/rate-limiting.md): límites, encabezados y el cuerpo de `429`.
* [Autenticación de la API](https://docs.didit.me/es/getting-started/api-authentication.md): cómo enviar tu clave de API.
* [Pruebas en sandbox](https://docs.didit.me/es/integration/sandbox-testing.md): reproduce resultados sin datos reales ni facturación.
* [Webhooks](https://docs.didit.me/es/integration/webhooks.md): entrega, reintentos y orden.


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