---
title: Códigos de error
description: Catálogo consolidado de códigos de error HTTP y de plataforma para los contratos Web & SDK, API y Magic Link.
canonical: https://developer.unico.io/es/dual-api/developers/api-reference/error-codes
locale: es
generated_by: markdown-export
---

- [/es/](/es/)
- [Referencia de API](/es/dual-api/developers/api-reference/)
- Códigos de error

**En esta página# 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](/es/dual-api/developers/sdks-and-tools/web/web-sdk/error-handling) de cada SDK; esta página cubre los errores a nivel del contrato de API.
### Códigos de estado HTTP​

CódigoSignificadoDó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](/es/dual-api/developers/api-reference/api/get-process).Endpoints de obtención de documentos; API Obtener proceso.`429 Too Many Requests`Se alcanzó el [límite de tasa](/es/dual-api/developers/api-reference/rate-limits). 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`)​

CausaSíntomaClave 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 correctasHeader `APIKEY` ausente (solo contrato API)`401``x-api-key` inválido (solo Magic Link)`401`
Ver [Autenticación > Errores comunes](/es/dual-api/developers/api-reference/authentication#error-codes) 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:
CampoValor negativoDónde aparece`process.result``PROCESS_RESULT_FAILED`Web & SDK`process.authenticationInfo.livenessResult``NO`Web & SDK`liveness``2`API`unicoId.result``no`API`data.response.unico.result``NOT_APPROVED`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)NoLa solicitud es incorrecta. Corrige la entrada antes de reintentar.`401`CondicionalmenteRefresca el token de acceso una vez. Si la nueva solicitud también devuelve `401`, el problema es estructural — no reintentar.
IdempotenciaLa 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](/es/dual-api/developers/sdks-and-tools/web/web-sdk/error-handling)
[Android SDK > Manejo de errores](/es/developers/sdks-and-tools/android/error-handling)
[iOS SDK > Manejo de errores](/es/developers/sdks-and-tools/ios/error-handling)
[Flutter SDK > Manejo de errores](/es/developers/sdks-and-tools/flutter/error-handling)

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í.Última actualización el 8 oct 2026**