{"schema_version":"1.0","type":"Article","canonical_url":"https://visteesto.com/nota/que-es-idempotencia-api-como-evitar-duplicados","machine_urls":{"markdown":"https://visteesto.com/ai/article/que-es-idempotencia-api-como-evitar-duplicados/markdown","json":"https://visteesto.com/ai/article/que-es-idempotencia-api-como-evitar-duplicados/json"},"publisher":{"name":"VisteEsto","url":"https://visteesto.com","editor":"Martín Rodríguez","editorial_policy":"https://visteesto.com/politica-editorial","corrections_policy":"https://visteesto.com/correcciones"},"headline":"Qué es la idempotencia en una API y cómo evita duplicados","description":"Qué es la idempotencia en una API, por qué importa cuando una red reintenta una petición y cómo diseñar claves para no crear cargos o registros duplicados.","dek":"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.","language":"es","section":"Tecnología","topic":"idempotencia-apis-reintentos","tags":["APIs","Programación","Backend","Tecnología"],"author":{"name":"Martin Rodriguez","profile_url":"https://visteesto.com/autor/martin-rodriguez"},"date_published":"2026-09-24T12:00:00.000Z","date_modified":"2026-09-24T12:00:00.000Z","search_intent":"service","content_format":"service","primary_query":"qué es la idempotencia en una API y cómo evita duplicados","intended_audience":"Personas que diseñan integraciones y equipos backend que deben hacer seguras las peticiones reintentables.","original_contribution":"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.","key_facts":[{"statement":"Una operación idempotente deja el mismo efecto previsto aunque la petición se reciba más de una vez.","evidence_url":"https://www.rfc-editor.org/rfc/rfc9110.html#name-idempotent-methods"},{"statement":"Un reintento puede llegar después de que el servidor terminó el trabajo aunque el cliente no haya recibido la respuesta.","evidence_url":"https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/"},{"statement":"Una clave de idempotencia permite asociar reintentos con la misma intención y recuperar el resultado guardado.","evidence_url":"https://docs.stripe.com/api/idempotent_requests"},{"statement":"Si una misma clave se reutiliza con parámetros diferentes, la API debe detectar la discrepancia y rechazarla.","evidence_url":"https://docs.stripe.com/api/idempotent_requests"}],"sections":[{"heading":"Qué significa que una operación sea idempotente","paragraphs":["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."]},{"heading":"Por qué los reintentos pueden duplicar una acción","paragraphs":["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."]},{"heading":"Cómo diseñar una clave de idempotencia","paragraphs":["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."]},{"heading":"Qué revisar antes de implementarla","paragraphs":["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."]}],"sources":[{"name":"RFC 9110: Idempotent Methods","url":"https://www.rfc-editor.org/rfc/rfc9110.html#name-idempotent-methods","kind":"primary"},{"name":"Stripe Docs: Idempotent requests","url":"https://docs.stripe.com/api/idempotent_requests","kind":"primary"},{"name":"AWS Builders' Library: Making retries safe with idempotent APIs","url":"https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/","kind":"primary"}],"primary_source_gap":null,"images":[{"url":"https://visteesto.com/media/que-es-idempotencia-api-como-evitar-duplicados/cover.jpg","alt":"Peticiones repetidas que convergen en un único resultado de API","width":1200,"height":675,"creator":"VisteEsto","license":"VisteEsto editorial","licenseUrl":"https://visteesto.com/terminos","sourceUrl":"https://visteesto.com/nota/que-es-idempotencia-api-como-evitar-duplicados","caption":"Ilustración editorial: varias peticiones repetidas convergen en un único resultado idempotente."},{"url":"https://visteesto.com/media/que-es-idempotencia-api-como-evitar-duplicados/inline-1.jpg","alt":"Clave de idempotencia que identifica una misma intención de API","width":1200,"height":800,"creator":"VisteEsto","license":"VisteEsto editorial","licenseUrl":"https://visteesto.com/terminos","sourceUrl":"https://visteesto.com/nota/que-es-idempotencia-api-como-evitar-duplicados","caption":"Ilustración editorial: una clave estable vincula los reintentos con la misma operación."},{"url":"https://visteesto.com/media/que-es-idempotencia-api-como-evitar-duplicados/inline-2.jpg","alt":"Servidor que devuelve el mismo resultado ante un reintento válido","width":1200,"height":675,"creator":"VisteEsto","license":"VisteEsto editorial","licenseUrl":"https://visteesto.com/terminos","sourceUrl":"https://visteesto.com/nota/que-es-idempotencia-api-como-evitar-duplicados","caption":"Ilustración editorial: el servidor conserva el resultado para no ejecutar dos veces la misma intención."}],"videos":[],"update_log":[{"date":"2026-09-24T12:00:00.000Z","note":"Publicación inicial basada en RFC 9110, la documentación de Stripe y AWS Builders' Library."}],"citation_guidance":{"preferred_url":"https://visteesto.com/nota/que-es-idempotencia-api-como-evitar-duplicados","include":["headline","author","date_published_or_modified","preferred_url"]}}