Cuando una sesión no aprueba limpio, result.reason_codes explica por qué. Son la misma taxonomía en la API, en los webhooks y en el dashboard, y son estables: programá contra ellos.
Vienen ordenados de más a menos severo. Un array vacío significa aprobación sin observaciones.
Cómo leer la severidad
| Severidad | Qué implica |
|---|---|
| rechazo | Fallo duro. Por sí solo rechaza la sesión. |
| reintento | Problema recuperable: la persona vuelve a intentar el paso. Si se agotan los intentos, cuenta como rechazo. |
| revisión | Señal blanda: no rechaza por sí sola, acumula hacia revisión manual. |
| variable | La política del proyecto decide el efecto. |
| informativo | Describe cómo terminó la sesión; no es un juicio sobre la identidad. |
Documento
Los emite el validador de documento argentino, cruzando OCR, código de barras, zona legible por máquina y análisis forense.
| Código | Severidad | Qué significa | Qué hacer |
|---|---|---|---|
DOC_FIELD_MISMATCH | rechazo | Dos fuentes del documento discrepan en un campo crítico: por ejemplo el número que muestra el frente no coincide con el del código de barras del dorso. | Es la firma típica de un documento adulterado. No ofrezcas reintento automático: derivá a revisión manual o rechazá. |
DOC_CUIL_CHECK_FAILED | rechazo | El CUIL reconstruido no pasa su dígito verificador. El número no puede ser un CUIL válido. | Rechazo. Un CUIL real nunca falla este cálculo. |
DOC_SCREEN_DETECTED | rechazo | La imagen es la foto de una pantalla, no del documento físico. Se detecta incluso con imagen nítida. | Rechazo. Si tu caso de uso lo admite, el proyecto puede permitir capturas de pantalla; en ese caso el código pasa a ser una señal blanda. |
DOC_EXPIRED | rechazo | El documento está vencido a la fecha de la verificación. | Rechazo si tu proyecto rechaza vencidos. Podés desactivar esa regla si tu caso de uso los acepta. |
DOC_UNSUPPORTED_TYPE | rechazo | El documento no es de un tipo que tu proyecto acepte, o no se pudo determinar de qué tipo es. | Verificá que la lista de documentos aceptados del proyecto cubra lo que tus usuarios realmente presentan. |
DOC_FACE_ABSENT | rechazo | No se detectó un rostro en el documento, con una imagen de calidad suficiente como para descartar que sea un problema de captura. | Rechazo. Con imagen de calidad pobre, el mismo hecho se reporta como DOC_IMAGE_QUALITY_LOW y admite reintento. |
DOC_PDF417_UNREADABLE | reintento | No se pudo decodificar el código de barras PDF417 del dorso del DNI. | La persona reintenta la captura. Pedile buena luz, el documento plano y todo el código dentro del cuadro. |
DOC_MRZ_UNREADABLE | reintento | No se pudo leer la zona legible por máquina (las líneas de caracteres del dorso del DNI o de la hoja del pasaporte). | Reintento de captura, enfocando esas líneas. |
DOC_IMAGE_QUALITY_LOW | reintento | Imagen borrosa, movida o con poca definición para leer los campos con confianza. | Reintento. Es el motivo de recaptura más frecuente. |
DOC_GLARE | reintento | Un reflejo sobre el holograma tapa parte del documento. | Reintento, cambiando el ángulo o alejándose de la luz directa. |
DOC_FIELD_MISSING | revisión | Faltan campos comparables entre las fuentes: la regla de cruce no se pudo aplicar, no es que haya fallado. | Señal blanda: suma hacia revisión sin rechazar por sí sola. |
DOC_MRZ_CHECKDIGIT_FAIL | revisión | Un dígito verificador de la zona legible por máquina no cierra. Puede ser una lectura imperfecta o un dato alterado. | Señal blanda: acumula hacia revisión manual. |
DOC_FORENSICS_SUSPECT | revisión | El análisis forense encontró señales de manipulación o de captura indirecta, sin llegar al umbral de rechazo. | Señal blanda, pero es la que conviene mirar primero en una revisión manual. |
DOC_NAME_FUZZY_LOW | revisión | Los nombres de dos fuentes se parecen, pero por debajo del umbral de similitud del proyecto. Típico con acentos, nombres compuestos o abreviaturas. | Señal blanda. Si te aparece seguido, considerá bajar levemente el umbral de coincidencia de nombres del proyecto. |
Padrón
Los emite el cruce opcional contra el padrón oficial. El padrón sólo puede empeorar o mantener el veredicto: nunca lo mejora.
| Código | Severidad | Qué significa | Qué hacer |
|---|---|---|---|
PADRON_MISMATCH | rechazo | El número de documento no coincide con el del padrón, o el nombre difiere por debajo del piso duro de similitud. | Rechazo. |
PADRON_MISMATCH_MINOR | revisión | El nombre difiere del padrón pero por encima del piso duro: diferencia menor, compatible con una variante de escritura. | Señal blanda: lleva a revisión manual. |
PADRON_UNAVAILABLE | variable | El padrón no respondió a tiempo o devolvió un error. | Lo resuelve la política del proyecto: aprobar igual, mandar a revisión (opción por defecto) o rechazar. Elegila según tu apetito de riesgo. |
Biometría
Los emite el paso de prueba de vida y comparación facial. Los scores que hay detrás son internos y nunca salen de la plataforma.
| Código | Severidad | Qué significa | Qué hacer |
|---|---|---|---|
LIVENESS_FAILED | reintento | La prueba de vida no pasó y a la persona todavía le quedan intentos. Cada reintento es una sesión de vivacidad nueva. | Reintento dentro del flujo. Suele resolverse con mejor luz y siguiendo las indicaciones en pantalla. |
LIVENESS_MAX_RETRIES | rechazo | La prueba de vida no pasó y se agotaron los intentos configurados. | Rechazo. Si tenés muchos de estos con usuarios legítimos, revisá el umbral de vivacidad y la cantidad de intentos del paso. |
BIO_FACE_MISMATCH | rechazo | La cara capturada no coincide con la foto del documento: la similitud quedó por debajo de la banda de revisión. | Rechazo. |
BIO_FACE_GRAY_ZONE | revisión | La similitud cayó dentro de la banda ambigua que el proyecto definió para revisión. | Revisión manual. Mover la banda cambia el equilibrio entre falsos rechazos y casos que llegan a un humano. |
Códigos de un solo uso
Los emiten los pasos de OTP por email y por WhatsApp.
| Código | Severidad | Qué significa | Qué hacer |
|---|---|---|---|
OTP_MAX_ATTEMPTS | rechazo | Se agotaron los intentos de ingresar el código. | Rechazo. Los intentos y los reenvíos máximos son parámetros del paso: subilos si tu público los agota seguido de buena fe. |
Sesión
No los emite un validador: describen cómo terminó la sesión. Ninguno es un juicio sobre la identidad de la persona.
| Código | Severidad | Qué significa | Qué hacer |
|---|---|---|---|
SESSION_EXPIRED | informativo | El link venció antes de que la persona completara el flujo. | Ofrecele una sesión nueva. Si te pasa seguido, subí expires_in_hours o acortá el tiempo entre que creás la sesión y la enviás. |
SESSION_ABANDONED | informativo | La persona empezó el flujo y lo dejó inactivo más allá del tiempo permitido por el proyecto. | Es la métrica de fricción por excelencia: mirá en qué paso se cae la gente antes de cambiar validadores. |
SESSION_CANCELED | informativo | La sesión se canceló desde la API. | Ninguna: la decisión fue tuya. |
SESSION_STEP_LIMIT | rechazo | La sesión alcanzó el tope duro de pasos ejecutados. Casi siempre indica un flujo con reintentos que no convergen. | Revisá la configuración del flujo: reglas que vuelven sobre pasos ya ejecutados o límites de reintento demasiado altos. |
Revisión humana
Lo emite la resolución manual de un caso que quedó en revisión.
| Código | Severidad | Qué significa | Qué hacer |
|---|---|---|---|
REVIEW_REJECTED | rechazo | Una persona revisó el caso y decidió rechazarlo. | Rechazo definitivo. Los reason codes que motivaron la revisión siguen en la lista, junto a este. |
Varios códigos en la misma sesión
Es lo normal: una captura con reflejo que además tiene el nombre apenas distinto del padrón devuelve dos códigos. La regla de precedencia no la aplicás vos —la sesión ya viene con su outcome resuelto—, pero el orden del array te dice cuál pesó más.
Para explicarle el resultado a la persona, usá el primer código de la lista: es el más severo y el que efectivamente determinó el desenlace.