Solución de problemas con errores de la API de Pleo

La solicitud no es válida o no supera la validación.

• Lee el cuerpo de la respuesta para identificar campos que faltan o valores no válidos.
• Compara tu solicitud con la documentación del endpoint. Comprueba los campos requeridos, la estructura de la solicitud, los formatos de fecha y los valores permitidos.
• Corrige el problema identificado e intenta de nuevo la solicitud.

No se ha podido autenticar la solicitud.

• Haz coincidir la credencial con la API y el entorno. Comprueba el host de la solicitud con la documentación para desarrolladores. No mezcles credenciales de la API nueva y la API antigua, ni credenciales de pruebas y producción.
• Comprueba el encabezado de autorización (`Authorization`). Las claves API nueva usan autenticación básica, con la clave como nombre de usuario y una contraseña vacía. Los tokens de acceso OAuth usan autenticación Bearer. Sigue la documentación de la API antigua para los tokens antiguos. Elimina los espacios o saltos de línea accidentales de las credenciales.
• Comprueba el estado de la credencial. Confirma que no haya expirado ni se haya revocado. Para OAuth, usa el token de acceso, no el token de actualización, y comprueba que el flujo de actualización del token funcione.

La solicitud se ha autenticado, pero el acceso no está permitido.

• Comprueba los ámbitos. Compara los ámbitos asignados a tu credencial con los requeridos por el endpoint. Si no puedes verlos, pide a la persona que gestiona la credencial que los confirme.
• Comprueba la empresa y el entorno. La credencial debe coincidir con la empresa o entidad cuyos datos solicitas y con el entorno al que llamas.
• Comprueba la disponibilidad del endpoint. Confirma en la documentación para desarrolladores que el endpoint sea compatible con tu método de autenticación y caso de uso.

Si coinciden, pero se sigue denegando el acceso, contacta con el soporte técnico para confirmar el acceso de API de la empresa. Indica si la misma credencial funciona en otros endpoints.

No se ha podido encontrar el endpoint o recurso solicitado.

• Compara la URL base, la versión de la API y la ruta del endpoint con la documentación para desarrolladores.
• Confirma que el ID del recurso identifica el recurso que querías solicitar.
• Comprueba que el recurso pertenezca a la empresa y al entorno asociados a la credencial. No mezcles ID de pruebas y producción.

Un recurso puede devolver un 404, aunque exista en Pleo si pertenece a otra empresa o entorno.

La solicitud entra en conflicto con una operación o estado existente.

• Lee la respuesta de error y comprueba si ya se ha enviado la misma operación. Revisa la respuesta anterior o la operación resultante antes de volver a enviarla.
• Sigue las indicaciones sobre conflictos e idempotencia del endpoint en la documentación para desarrolladores.

Tu integración está enviando solicitudes con demasiada frecuencia.

• Consulta los encabezados de respuesta para ver indicaciones sobre reintentos o límites de tasa.
• Reduce la frecuencia de las solicitudes y evita reintentos inmediatos en un bucle cerrado.
• Usa una espera exponencial, siguiendo las indicaciones de reintentos del endpoint.

Si esto continúa con un volumen bajo de solicitudes, incluye la frecuencia de tus solicitudes y el comportamiento de reintento al contactar con el soporte técnico.

Se produjo un error del servidor. Recopila la respuesta de error y los detalles de la solicitud indicados en “¿Aún necesitas ayuda?” y contacta con el soporte técnico. Indica si ocurrió una sola vez o se repite.

Si los eventos de webhook no llegan a tu integración o esta no los procesa:

• Comprueba la accesibilidad. Tu endpoint de recepción debe ser accesible públicamente a través de HTTPS y no debe bloquear las solicitudes de Pleo.
• Comprueba los registros de entrega. Busca el intento de entrega, el estado de la respuesta y el tiempo de respuesta. Devuelve una respuesta 2xx sin demora, siguiendo los requisitos de la documentación del webhook.
• Comprueba la verificación de la firma. Utiliza el cuerpo de la solicitud en el formato requerido por la documentación del webhook, incluido el cuerpo sin procesar cuando se especifique.
• Gestiona las entregas duplicadas de forma segura. Elimina duplicados mediante el identificador de evento o webhook especificado en la documentación.

Después de hacer un cambio, comprueba una entrega posterior. Si sigue fallando, incluye el ID de la suscripción, el ID del evento o webhook, la marca de tiempo de entrega, el estado de respuesta del endpoint y los registros depurados al contactar con el soporte técnico.