Códigos de error
Esta página es la fuente de verdad para el manejo de errores. Los códigos de error específicos de cada SDK están documentados en la página de Manejo de errores de cada SDK; esta página cubre los errores a nivel del contrato de API.
Códigos de estado HTTP
| Código | Significado | Dónde aplica |
|---|---|---|
200 OK | La solicitud fue exitosa. | Todos los contratos. |
201 Created | Recurso creado (poco frecuente; la mayoría de las creaciones devuelven 200). | Contrato API. |
400 Bad Request | El payload está malformado o faltan campos requeridos. El cuerpo identifica los campos problemáticos. | Todos los contratos. |
401 Unauthorized | Autenticación ausente, expirada o inválida. | Todos los contratos. |
403 Forbidden | La autenticación es válida pero el tenant no está habilitado para el recurso solicitado (por ejemplo, invocar una capacidad que no está en tu APIKEY). | Web & SDK, API. |
404 Not Found | El recurso no existe o no pertenece al tenant autenticado. | Todos los contratos. |
409 Conflict | El recurso existe pero no está en el estado correcto para esta operación (por ejemplo, obtener documentos de un proceso aún en curso). | Web & SDK, API. |
410 Gone | El recurso existía pero fue eliminado según la política de retención (endpoints de obtención de documentos), o el proceso existe pero terminó en estado de error — ver Obtener proceso. | Endpoints de obtención de documentos; API Obtener proceso. |
429 Too Many Requests | Se alcanzó el límite de tasa. Reintenta con retroceso exponencial. | Todos los contratos. |
5xx | Error de plataforma. Reintenta con retroceso; si persiste, contacta soporte con el cuerpo de respuesta y la marca de tiempo. | Todos los contratos. |
Errores de autenticación (401)
| Causa | Síntoma |
|---|---|
| Clave privada incorrecta (aserción firmada con la clave equivocada) | 401, Authentication failed (1.2.21) |
aud no coincide con la URL del entorno | 401 |
Claim exp en el pasado | 401, Authentication failed |
Algoritmo no compatible (usar RS256) | 401 |
| Mezcla de credenciales de sandbox / producción | 401, incluso cuando las credenciales parecen correctas |
Header APIKEY ausente (solo contrato API) | 401 |
x-api-key inválido (solo Magic Link) | 401 |
Ver Autenticación > Errores comunes para la lista de verificación completa de solución de problemas.
Resultados a nivel de capacidad (200 con resultado negativo)
Un 200 OK no significa que el usuario pasó la verificación — significa que la plataforma completó el trabajo. La decisión visible para el usuario se encuentra en el cuerpo de la respuesta, no en el estado HTTP:
| Campo | Valor negativo | Dónde aparece |
|---|---|---|
process.result | PROCESS_RESULT_FAILED | Web & SDK |
process.authenticationInfo.livenessResult | NO | Web & SDK |
liveness | 2 | API |
unicoId.result | no | API |
data.result.status | not_verified | Magic Link |
Política de reintentos
| Estado | ¿Debería reintentar? | Cómo |
|---|---|---|
5xx | Sí | Retroceso exponencial (1s, 2s, 4s, 8s, …). Máximo 5 intentos. |
429 | Sí | Respetar el header Retry-After si está presente; de lo contrario, retroceso exponencial. |
4xx (otros) | No | La solicitud es incorrecta. Corrige la entrada antes de reintentar. |
401 | Condicionalmente | Refresca el token de acceso una vez. Si la nueva solicitud también devuelve 401, el problema es estructural — no reintentar. |
La plataforma IDCloud actualmente no expone un mecanismo de clave de idempotencia en los endpoints de creación. Ten cuidado al reintentar POST /client/v1/process o POST /processes/v1 — un error de red en un 5xx puede haber tenido éxito en el servidor, y un reintento crearía un proceso duplicado. En caso de duda, recupera los procesos recientes por tu ID de correlación interno antes de reintentar.
Dónde encontrar los errores de SDK
Los catálogos de errores del Web SDK, Android SDK, iOS SDK y Flutter SDK están documentados en la página dedicada de Manejo de errores de cada SDK:
- Web SDK > Manejo de errores
- Android SDK > Manejo de errores
- iOS SDK > Manejo de errores
- Flutter SDK > Manejo de errores
Estos cubren errores del lado del dispositivo (permiso de cámara denegado, tiempo de espera de captura agotado, red no disponible en el dispositivo) — separados de los errores del lado de la API documentados aquí.