Errores de la API y qué significan
Qué suele significar en la práctica cada estado HTTP de la API de Didit - 401 y 403 sobre claves y permisos, problemas de saldo tipo 402, límites de frecuencia 429, y cómo leer el cuerpo del error.
Lee el cuerpo de la respuesta. Los errores de Didit llevan un mensaje y a menudo un código de detalle que nombra el problema real: el estado por sí solo rara vez basta. El 401 es la clave, el 403 son permisos o entorno, el 429 es límite de frecuencia, y un error de saldo son créditos, no código.
#Lee primero el cuerpo
El estado HTTP te dice la categoría. El cuerpo te dice qué ha pasado. Casi cada hora de depuración evitable en una integración de API se pierde adivinando a partir de un código de estado, mientras la respuesta estaba en un cuerpo que se descartó.
- Una clave desactivada o de una aplicación equivocada es la causa habitual de un 401.
- Último uso confirma si la clave que crees estar enviando es la que realmente llega.
- Rota el secreto si una clave puede haberse filtrado: un 401 es mejor que una brecha.
Registra el cuerpo completo del error (estado, cabeceras y payload) en cada llamada fallida, en cada entorno. Lo vas a necesitar, y es mucho más difícil de reconstruir después.
#Qué suele significar cada estado
| Estado | Causa habitual |
|---|---|
| 400 | Una solicitud malformada: falta un campo obligatorio, un valor de enum incorrecto, un objeto anidado con forma incorrecta |
| 401 | Falló la autenticación. Falta la cabecera x-api-key, está malformada, o no es una clave válida |
| 403 | Autenticado pero no permitido. Entorno equivocado, un permiso que tu clave no tiene, o una función no activada en tu cuenta |
| 404 | El recurso no existe, o existe bajo una aplicación distinta de la de la clave que usaste |
| 409 | Un conflicto con el estado existente, como una acción que ya se ha realizado |
| 422 | La solicitud estaba bien formada pero los valores no son aceptables: un fallo de validación, no de sintaxis |
| 429 | Límite de frecuencia alcanzado. Ver más abajo |
| 5xx | Un problema del lado de Didit. Reintenta con backoff, y consulta status.didit.me |
#401 frente a 403: la distinción que ahorra tiempo
401 significa que la clave no se aceptó en absoluto. Comprueba que estás enviando x-api-key, que el valor no tiene espacios en blanco ni comillas sobrantes, y que no has pegado un secreto de firma de webhook en lugar de la clave de API: son cosas distintas y el error es común.
403 significa que la clave es válida pero esta llamada no está permitida. Tres causas, en orden:
- Desajuste de entorno. Los campos exclusivos de sandbox (como
sandbox_scenario) se rechazan en una aplicación en producción, y viceversa. Producción y sandbox son aplicaciones separadas con claves separadas. - Falta un permiso. Algunas operaciones necesitan permisos que tu clave o tu rol no tienen. Si necesitas derechos de creación y gestión de sesiones que no tienes, eso es una solicitud a soporte, no un arreglo de código.
- Función no activada. Algunas capacidades se aprovisionan por organización. Un 403 en una función que crees que deberías tener merece una consulta antes de reescribir la llamada.
No hay ninguna forma integrada de distinguir una clave de sandbox de una de producción con solo mirarla, así que guárdalas con nombres claramente distintos en tu gestor de secretos y nunca dejes que una sola variable de entorno contenga "la clave que toque en cada momento". Una clave de producción en un entorno de pruebas gasta créditos reales.
#Un 404 que debería existir
Si una sesión o un flujo de trabajo devuelve 404 y estás seguro de que existe, la respuesta habitual es que existe bajo una aplicación distinta de la de la clave con la que te autenticaste. Los recursos están delimitados a su aplicación; una clave de la aplicación A no puede ver las sesiones de la aplicación B.
#Errores de saldo y créditos
Una llamada que falla porque no hay créditos suficientes no es un problema de código. El flujo de trabajo contiene una función de pago y tu saldo no la cubre. Este es, con diferencia, el informe más habitual de "la API se ha roto", y la causa casi siempre es white label, AML o NFC en un flujo de trabajo que se esperaba que fuera gratis. Consulta cómo solucionar un error de "créditos insuficientes".
#Límite de frecuencia 429
Los límites se aplican por identificador: tu x-api-key, o tu IP de cliente si no se envía ninguna clave, con un contador independiente por ámbito en una ventana móvil de 60 segundos.
Valores globales por defecto:
| Ámbito | Métodos | Límite |
|---|---|---|
| Lecturas genéricas | GET | 600 / min |
| Escrituras genéricas | POST, PATCH, DELETE | 300 / min |
Algunos endpoints de alto impacto tienen límites más estrictos además del global, y el primer ámbito que supere su contador es el que devuelve 429. Tabla completa: límites de frecuencia.
Gestiona el 429 con backoff exponencial y jitter. Un bucle de reintentos ajustado contra un límite de frecuencia empeora el problema y puede mantenerte limitado indefinidamente.
Los trabajos por lotes son la fuente habitual de un 429: una importación nocturna que dispara varios cientos de creaciones en pocos segundos. Reparte el trabajo en lugar de subir la concurrencia hasta que deje de dar error.
#Códigos de detalle a nivel de función
Más allá de los estados HTTP, cada comprobación devuelve sus propios códigos de detalle para problemas a nivel de proveedor: por ejemplo, una integración de registro que no tiene acceso a un producto concreto en un país concreto. Cuando recibas uno, el código nombra la situación con precisión, así que cítalo cuando preguntes por él.
Si una respuesta omite un código de detalle que esperarías del catálogo, merece la pena reportarlo en lugar de buscar un rodeo: un código ausente es un hueco real, y hace el mismo problema más difícil para la siguiente persona.
#Una respuesta vacía no es un éxito
Una comprobación respaldada por un proveedor que devuelve un cuerpo vacío no es lo mismo que un resultado limpio. Trata "sin datos" como su propio caso en tu código en lugar de asignarlo a un aprobado, especialmente en validación de base de datos y cribado de carteras, donde un servicio no aprovisionado y una ausencia de coincidencia genuina pueden parecer iguales desde fuera.
#Probar rutas de error
Sandbox fuerza fallos concretos de forma determinista, que es la única manera sensata de probar tu gestión de errores. Consulta probar en sandbox.