La idempotencia ayuda a diseñar APIs que sean resistentes a fallas de red y tiempos de espera. Sin idempotencia, reintentar una operación de que crea recursos o modifica datos puede crear clientes, facturas o pagos duplicados.
Para evitarlo, envía un X-Idempotency-Key único en cada operación lógica que use POST, PUT, PATCH o DELETE.
Cómo usar
Genera una clave antes de enviar la solicitud y guárdala junto con el trabajo pendiente en tu sistema. Reutiliza exactamente la misma clave si necesitas reintentar esa operación. Recomendamos usar un UUID; la clave debe tener entre 1 y 200 caracteres.
Si tu cliente agota el tiempo de espera o pierde la respuesta, repite la misma solicitud con la misma clave.
Qué considera la misma solicitud
Una clave se asocia con el método HTTP, la ruta, los parámetros de consulta y el cuerpo de la solicitud. El primer uso de la clave fija esa combinación.
- Repite la misma operación con la misma clave, ruta, parámetros y cuerpo.
- Usa una clave nueva para otra factura, pago o cambio de datos.
- No reutilices una clave con un cuerpo, parámetros o ruta distintos. Quentli devuelve
409 Conflict para evitar una operación ambigua.
Respuestas y reintentos
Quentli conserva por 24 horas la respuesta de una solicitud idempotente que termina entre 200 y 499. Un reintento idéntico devuelve el mismo código y cuerpo, junto con el encabezado:
Quentli reserva la clave durante 60 segundos mientras procesa la primera solicitud. Si un reintento llega en ese periodo, devuelve 409 Conflict. Espera y vuelve a intentar con la misma clave y la misma solicitud.
Las respuestas 4xx también se conservan. Si corriges la solicitud después de un error de validación o autorización, crea una clave nueva para la solicitud corregida.
Las respuestas 5xx no se conservan. Después de un error de servidor, el resultado de la operación puede ser
indeterminado. Consulta el estado del recurso o contacta a soporte antes de repetir una operación que pudiera haber
creado un cobro o una factura.
