Idempotencia

Una operación es idempotente si repetirla tiene el mismo efecto en el servidor que hacerla una sola vez. Importa porque las redes fallan: un cliente que recibe un timeout no sabe si su petición llegó, y reintentar solo es seguro cuando la petición es idempotente. La idempotencia trata del estado del servidor, no de obtener una respuesta idéntica cada vez.

Qué métodos HTTP son idempotentes

Método	Idempotente	Seguro (sin efectos secundarios)
GET, HEAD, OPTIONS	Sí	Sí
PUT	Sí	No
DELETE	Sí	No
POST	No	No
PATCH	No garantizado	No

DELETE /orders/42 enviado dos veces puede devolver 204 y luego 404. Las respuestas son distintas, pero el estado es el mismo: el pedido ya no existe. Sigue siendo idempotente.

PUT frente a PATCH

PUT reemplaza el recurso completo por el cuerpo que envías. Enviar PUT /users/7 con {"name": "Ada", "plan": "pro"} tres veces deja el mismo usuario cada vez, así que es idempotente.

PATCH aplica un cambio, y que sea idempotente depende del cambio. {"plan": "pro"} fija un valor y en la práctica es idempotente. Una operación como “incrementar loginCount en 1”, o un add de JSON Patch sobre un array, da un resultado distinto cada vez, así que PATCH como método no garantiza la idempotencia.

Cómo hacer que un POST se pueda reintentar con seguridad

Las APIs de pagos y pedidos suelen aceptar una clave de idempotencia: el cliente genera un valor único y lo envía en una cabecera como Idempotency-Key. El servidor guarda el resultado de la primera petición con esa clave y devuelve el mismo resultado ante cualquier repetición, en lugar de crear un segundo pedido.

POST /payments HTTP/1.1
Content-Type: application/json
Idempotency-Key: 6f1c2a9e-3b7d-4f0a-9c2e-1d5b8a7e4f60

{"amount": 4999, "currency": "EUR"}

Cómo probarla

• Envía el mismo PUT o DELETE dos veces y comprueba el estado del recurso, no solo el código de estado.
• Envía el mismo POST con la misma clave de idempotencia dos veces. Espera un único recurso y el mismo cuerpo de respuesta.
• Reutiliza una clave con un cuerpo distinto. Una API bien diseñada lo rechaza en lugar de devolver en silencio el resultado anterior.
• Lanza peticiones duplicadas de forma concurrente. Las condiciones de carrera son donde suele romperse el manejo de la idempotencia.