Errores y recuperación
En esta página
Gestiona los errores sin adivinar si se completó una escritura.
Conserva un contexto de soporte seguro
Conserva el requestId o X-Request-Id seguro para soporte, junto con la operación y la hora. No incluyas credenciales, datos de solicitantes ni URL de documentos en los registros.
Responde a los errores HTTP
| Respuesta | Siguiente acción |
|---|---|
| 400 / 422 | Corrige la solicitud según el esquema y el código de error de la operación; no repitas una entrada no válida sin modificarla. |
| 401 | Detente y pide al administrador que compruebe si falta la clave o si no es válida, ha caducado o está revocada. |
| 403 | Comprueba el permiso requerido y el alcance de empresa. No solicites automáticamente un acceso más amplio. |
| 404 | Comprueba el ID del recurso devuelto y la tarea. Cambiar un ID no permite acceder al recurso de otra empresa. |
| 409 | Lee el código de error y la versión actual del recurso, previsualización o formulario. Resuelve el conflicto antes de otra modificación. |
| 410 | Sigue el significado de la operación: un cursor de sincronización caducado requiere una nueva sincronización completa; una solicitud eliminada no debe recrearse mediante una repetición antigua. |
| 429 | Respeta Retry-After cuando se proporcione y X-RateLimit-Reset; aplica esperas limitadas con variación aleatoria. |
| Tiempo de espera agotado / 5xx temporal | Considera desconocido el resultado de una escritura. Consulta mediante el ID conocido o repite con la clave original dentro de la ventana de 24 horas, con esperas limitadas. No crees una operación nueva. |
Recupera una escritura de resultado desconocido
Tras perder una respuesta, consulta el recurso o la operación si conoces el ID devuelto. Si no conoces ningún ID devuelto, repite la solicitud idéntica con el Idempotency-Key original y la clave API original dentro de las 24 horas siguientes al primer intento. Si esa ventana ha vencido o no hay una consulta o repetición segura disponible, detente y determina el resultado; ni reutilizar una clave caducada ni elegir una nueva garantiza que la escritura no vuelva a ejecutarse. Las previsualizaciones de importación, los trabajos y su historial siguen vinculados a la clave que los creó.
Rota y retira las credenciales
Para rotar una clave, crea otra con los mismos permisos o menos, impleméntala en la integración y verifica una consulta autenticada. Antes de revocar la anterior, termina o determina el resultado de sus previsualizaciones y trabajos pendientes utilizando la clave anterior. La clave de sustitución no hereda sus ID de trabajo ni su historial. Después, revoca la clave anterior. El administrador utiliza Configuración → API y agentes o su plano de control autenticado /api/v1/settings/api-keys. Una clave de integración de empresa no es una sesión de administrador. Los ID de clave son referencias no secretas, no credenciales; la clave en texto sin procesar no puede recuperarse más adelante. Verifica que se rechaza la clave retirada.
Usa la versión publicada del contrato
Usa la versión de API y el ciclo de vida indicados en la referencia, los esquemas de cada operación y cualquier versión de formulario o recurso requerida al actualizar una integración. Conserva las versiones opacas sin cambios y fija una versión MCP aprobada. Los nombres de evento proceden del mismo catálogo que la API; el orden de llegada y una versión de producto no sustituyen la consulta actual del recurso.