Fluyio Developers

Reutiliza una clave por operación y evita repetir escrituras cuando la respuesta se pierde.

Una espera agotada no demuestra que una escritura haya fallado. Envía Idempotency-Key para identificar una operación y reutiliza la misma clave y petición en sus reintentos.

Primera petición

curl -X POST 'https://fluyio.com/api/v1/subscribers' \
  -H "Authorization: Bearer $FLUYIO_API_KEY" \
  -H 'Fluyio-Version: 2026-05-15' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: crm-perfil-123-revision-1' \
  -d '{"email":"[email protected]","first_name":"Ana"}'

Este ejemplo crea un perfil pendiente, sin consentimiento para email. Solo debes enviar consent.email: subscribed si tienes una autorización explícita y válida.

Cómo funciona

Tras comprobar autenticación y permisos, el servidor reserva atómicamente la clave en Redis durante 24 horas.
Si puede reservarla, ejecuta la operación. Guarda su respuesta 2xx o 4xx antes de devolverla.
Una repetición con la misma petición devuelve el resultado guardado y la cabecera Idempotency-Replayed: true.
Una petición simultánea o con resultado incierto no vuelve a ejecutar la escritura.
Al caducar la reserva, una nueva petición puede ejecutarse. No reutilices claves antiguas para reintentos sin comprobar primero el resultado.

Contrato

Propiedad	Valor
Métodos	`POST`, `PATCH`, `PUT` y `DELETE`. No hay ruta PUT publicada. GET ignora la cabecera.
Formato	De 8 a 128 letras ASCII, números, guiones o guiones bajos.
Obligatoriedad	Opcional. Sin cabecera no se aplica esta protección.
Ámbito	Marca, clave de API, método y ruta. Cambiar de clave de API cambia este ámbito.
Comparación	Cuerpo JSON, parámetros de consulta, versión y modo. El orden de claves de objetos no importa; el orden de arrays sí.
Caducidad	Reserva inicial de 24 horas; la respuesta completada se conserva 24 horas desde que se guarda.

Errores que debes distinguir

HTTP	Código	Significado
400	`invalid_idempotency_key`	Formato inválido. La operación no se ejecuta.
409	`idempotency_key_reuse`	La misma clave identifica otra petición. Una clave nueva solo corresponde a una operación nueva.
409	`idempotency_in_progress`	La operación está en curso o su resultado es incierto. Comprueba el recurso; no cambies de clave para forzarla.
409 / 503	`idempotency_record_unavailable`	No se puede recuperar con seguridad un registro previo, incluidos registros antiguos. Comprueba el resultado.
503	`idempotency_unavailable`	No se pudo reservar la operación. No se inicia una escritura sin protección; reintenta con la misma clave.
503	`idempotency_outcome_unknown`	La operación puede haberse aplicado, pero no se guardó la respuesta. Comprueba el recurso antes de repetir.

Un 5xx no implica que puedas ejecutar otra vez

Un error puede producirse después de escribir en la base de datos. En ese caso la reserva se mantiene para impedir que un reintento vuelva a modificar el recurso. Conserva la clave, revisa el estado del suscriptor y facilita el identificador de petición a soporte si necesitas ayuda. No cambies la clave para eludir la protección.

Límites de la garantía

La idempotencia no equivale a una garantía de ejecución exactamente una vez. La protección depende de conservar Redis y de que no haya caducado la reserva. Tampoco sustituye comprobar el resultado antes de repetir una operación mucho después o con otra credencial.

Las respuestas repetidas conservan el estado y los datos del resultado, pero el request_id de error y la cabecera de petición identifican el reintento actual.

Reglas prácticas

Genera la clave antes del primer intento y guárdala junto con el trabajo de tu cola.
Ante un 429, respeta Retry-After. Reutiliza la misma clave.
Ante pérdida de conexión, repite la misma petición de forma acotada; si recibes resultado incierto, consulta el recurso.
No elimines la cabecera ni cambies de credencial, URL o clave para forzar un reintento.
Antes de reintentar un borrado o un cambio de consentimiento, confirma el estado actual.

Consulta también errores y límites de peticiones.

Idempotencia y reintentos