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 |
|---|---|
200 OK | La solicitud fue exitosa. |
400 Bad Request | El payload está malformado o faltan campos requeridos. El cuerpo identifica los campos problemáticos. |
401 Unauthorized | Autenticación ausente, expirada o inválida. |
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). |
404 Not Found | El recurso no existe o no pertenece al tenant autenticado. |
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). |
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. |
429 Too Many Requests | Se alcanzó el límite de velocidad. Reintenta con retroceso exponencial. |
5xx | Error de plataforma. Reintenta con retroceso; si persiste, contacta soporte con el cuerpo de respuesta y la marca de tiempo. |
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 Crear proceso — 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 Android SDK, iOS SDK y Flutter SDK están documentados en la página dedicada de Manejo de errores de cada SDK:
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í.