# Qué es la idempotencia en una API y cómo evita duplicados > Una operación idempotente puede repetirse y dejar el mismo efecto final. Es una defensa práctica contra reintentos, cortes de conexión y usuarios que vuelven a enviar una petición. - URL canónica: https://visteesto.com/nota/que-es-idempotencia-api-como-evitar-duplicados - Autor: [Martin Rodriguez](https://visteesto.com/autor/martin-rodriguez) - Publicado: 2026-09-24T12:00:00.000Z - Actualizado: 2026-09-24T12:00:00.000Z - Sección: Tecnología - Tema: idempotencia-apis-reintentos - Idioma: es - Consulta principal: qué es la idempotencia en una API y cómo evita duplicados ## Resumen verificable - Una operación idempotente deja el mismo efecto previsto aunque la petición se reciba más de una vez. ([evidencia](https://www.rfc-editor.org/rfc/rfc9110.html#name-idempotent-methods)) - Un reintento puede llegar después de que el servidor terminó el trabajo aunque el cliente no haya recibido la respuesta. ([evidencia](https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/)) - Una clave de idempotencia permite asociar reintentos con la misma intención y recuperar el resultado guardado. ([evidencia](https://docs.stripe.com/api/idempotent_requests)) - Si una misma clave se reutiliza con parámetros diferentes, la API debe detectar la discrepancia y rechazarla. ([evidencia](https://docs.stripe.com/api/idempotent_requests)) ## Aporte editorial de VisteEsto VisteEsto organiza la implementación alrededor de la intención, la clave estable, la persistencia del resultado y los casos concurrentes que pueden producir duplicados. ## Qué significa que una operación sea idempotente Una operación es idempotente cuando una petición se repite una o varias veces y el efecto previsto sobre el servidor queda igual que después de una sola ejecución. La respuesta puede variar por el momento o incluir metadatos nuevos, pero el estado que importa para la operación no debe multiplicarse. La propiedad no describe si una petición es segura o si siempre devuelve el mismo código. Describe qué ocurre con el efecto acumulado. Por eso una lectura suele ser idempotente y una creación de recurso normalmente necesita una estrategia adicional si el cliente puede reintentarla. ## Por qué los reintentos pueden duplicar una acción Un cliente puede enviar una petición, perder la respuesta y no saber si el servidor terminó el trabajo. Si vuelve a enviarla sin una identidad para esa intención, la API puede crear dos órdenes, dos reservas o dos cargos. El corte no prueba que la primera ejecución haya fallado. La solución empieza por distinguir un reintento de una nueva operación. El cliente genera una clave única para esa intención y la conserva mientras repite la petición. El servidor registra la clave junto con el resultado y devuelve el mismo resultado cuando recibe de nuevo esa clave válida. ## Cómo diseñar una clave de idempotencia La clave debe ser única dentro del alcance que la API puede controlar y no debe cambiar entre reintentos de la misma acción. También conviene asociarla al usuario, cuenta o recurso que la ejecuta, validar que el cuerpo de la petición coincida y conservar el resultado durante una ventana documentada. Una clave no reemplaza la autorización ni la validación del pedido. El servidor debe comprobar permisos, importes y estado antes de ejecutar. Si una segunda petición usa la misma clave con parámetros diferentes, hay que rechazarla para que una identidad de operación no termine representando dos intenciones. ## Qué revisar antes de implementarla Definí qué efecto debe quedar una sola vez: crear un registro, confirmar un pago o publicar un evento. Después elegí dónde se guarda la clave y el resultado, qué pasa si dos reintentos llegan al mismo tiempo y cuánto dura la ventana de deduplicación. La respuesta debe permitir al cliente saber si puede continuar. También documentá qué métodos y endpoints aceptan reintentos y cuál es el comportamiento ante una clave vencida. Las pruebas deben cubrir un corte después de que el servidor persiste el resultado, dos peticiones concurrentes y una repetición con parámetros distintos. Así la idempotencia se comprueba en el límite donde realmente aparecen los duplicados. ## Fuentes consultadas - Fuente primaria: [RFC 9110: Idempotent Methods](https://www.rfc-editor.org/rfc/rfc9110.html#name-idempotent-methods) - Fuente primaria: [Stripe Docs: Idempotent requests](https://docs.stripe.com/api/idempotent_requests) - Fuente primaria: [AWS Builders' Library: Making retries safe with idempotent APIs](https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/) ## Imágenes y licencias - Peticiones repetidas que convergen en un único resultado de API. Autor: VisteEsto. Licencia: [VisteEsto editorial](https://visteesto.com/terminos). [Origen](https://visteesto.com/nota/que-es-idempotencia-api-como-evitar-duplicados). - Clave de idempotencia que identifica una misma intención de API. Autor: VisteEsto. Licencia: [VisteEsto editorial](https://visteesto.com/terminos). [Origen](https://visteesto.com/nota/que-es-idempotencia-api-como-evitar-duplicados). - Servidor que devuelve el mismo resultado ante un reintento válido. Autor: VisteEsto. Licencia: [VisteEsto editorial](https://visteesto.com/terminos). [Origen](https://visteesto.com/nota/que-es-idempotencia-api-como-evitar-duplicados). ## Cómo citar Citar título, autor, fecha de publicación o actualización y la URL canónica. Las afirmaciones centrales incluyen su evidencia directa arriba. Esta versión Markdown es una representación accesible; la nota HTML canónica es la fuente editorial de referencia.