Resumen

  • El borrador HTTPAPI sobre Idempotency-Key, ya vencido y archivado, atribuye a la fuente del recurso el ciclo de vida de las claves y su política de expiración. Los contratos actuales de Stripe y los ejemplos de AWS muestran límites de retención distintos, no un plazo universal.
  • Deben separarse la memoria de deduplicación y la autoridad para producir un efecto. Fuera de la ventana reconocida, una operación antigua e incierta debe consultarse, conciliarse o quedar pendiente; una clave ausente no demuestra que el primer efecto nunca ocurrió.

Un trabajo puede terminar y, aun así, dejar al cliente sin respuesta. Una conexión se pierde después de que el servidor haya aceptado una instrucción. El proceso cliente se detiene y vuelve días después. Conserva la petición y su clave de idempotencia, pero no sabe si la ejecución empezó, siguió en curso, falló o terminó. El servidor, entretanto, puede haber eliminado la entrada que le permitía reconocerla.

La segunda entrega contiene los mismos bytes. No contiene necesariamente una segunda decisión.

Ese contraste limita la promesa de los «reintentos seguros». Una clave ayuda a reconocer repeticiones dentro de un contrato. Si el contrato tiene un horizonte, la seguridad no se extiende sola más allá. Una cadena aleatoria no acredita la ausencia del efecto anterior ni expresa por sí misma una autorización renovada.

draft-ietf-httpapi-idempotency-key-header-07, publicado el 15 de octubre de 2025, describe una propuesta de cabecera estructurada, unicidad, huella opcional de la carga y tratamiento de duplicados. Su revisión 07 venció el 18 de abril de 2026. Datatracker la presenta como Internet-Draft archivado del grupo HTTPAPI; no es un RFC, un borrador activo ni una norma aprobada. El origen en un grupo de trabajo no autoriza a hablar de consenso establecido.

La propuesta sigue siendo útil para analizar el problema precisamente porque coloca la expiración dentro de la especificación de la fuente del recurso. No promete memoria infinita. Tampoco permite que un cliente general suponga que cualquier servidor respetará una clave que recibe. La garantía está en las reglas publicadas y en su realización concreta.

El tiempo de espera no identifica el estado

El RFC 9110 define la idempotencia de un método por el efecto previsto de su repetición. No exige respuestas idénticas ni elimina todos los efectos secundarios de observación. Mucho menos garantiza una ejecución exactamente una vez a través de sistemas distintos. Un POST o PATCH puede recibir un contrato idempotente del servicio, pero no adquiere esa propiedad global solo porque lleve una cabecera.

La respuesta perdida deja un problema de conocimiento. Antes de la aceptación, repetir puede ser lo adecuado. Durante el trabajo, puede ser necesario esperar o consultar. Después de la terminación, puede corresponder recuperar el resultado. Si hubo una consecuencia parcial en otro sistema, se necesita una conciliación más específica. Todos esos casos caben detrás del mismo timeout del cliente.

El borrador diferencia una petición inicial, una repetición después de terminar y una repetición concurrente. Para la segunda propone devolver el resultado anterior, sea éxito o error; para la concurrente, conflicto. También distingue el uso de la misma clave con otra carga. Esos estados no son excusas intercambiables para inventar una clave nueva y volver a actuar.

La comparación de cargas necesita, además, una semántica publicada. Una huella de toda la petición o de campos seleccionados puede servir, pero la elección define qué se considera la misma intención. Entropía y unicidad reducen colisiones; no resuelven una diferencia de significado omitida por la huella.

La retención forma parte del compromiso

Guardar cada clave, cuerpo y resultado para siempre tiene costes y riesgos. La política debe atender al uso de almacenamiento, privacidad, duración del recurso y llegadas tardías plausibles. El punto de gobernanza no es prohibir la limpieza. Es impedir que se confunda limpieza con autorización.

Stripe documenta un límite específico. Una vez iniciada la ejecución del punto de acceso, conserva el primer código de estado y cuerpo de una clave, incluidos errores. Si una validación falla o hay un conflicto concurrente antes de comenzar la ejecución, no se guarda ese resultado. Las claves pueden eliminarse cuando tienen al menos 24 horas; reutilizar una después de que se haya limpiado genera una petición nueva.

No significa que toda clave venza exactamente a las 24 horas. Tampoco describe la retención de otros proveedores ni prueba un incidente de cobro duplicado. Es un contrato que un cliente de ese servicio debe incorporar a su recuperación. Si la cola puede regresar después de varios días, no basta con que siga conservando el token original.

AWS ofrece en Builders Library un ejemplo distinto: una repetición tardía puede llegar después de que otro actor elimine el recurso creado. En su caso EC2, preserva una respuesta semánticamente equivalente en lugar de recrear ese recurso. Explica una retención ligada a la vida del recurso más un intervalo para llegadas tardías y señala que los requisitos varían entre servicios y recursos.

Sería un error convertir esos ejemplos en una regla común de duración. Un SDK con reintentos breves, un equipo desconectado, una restauración y un operador de soporte tienen horizontes diferentes. Hay que compararlos con el periodo de reconocimiento concreto. Más backoff no arregla una memoria que ya venció.

Cuatro identidades permiten una decisión mejor

La primera es la clave de deduplicación, válida en el alcance anunciado por el servicio. La segunda es la operación de negocio que una persona o sistema autorizó. La tercera es el efecto producido: recurso, modificación o instrucción ejecutada. La cuarta es una intención nueva que puede autorizar otro efecto.

Una clave distinta no demuestra intención distinta. La misma clave fuera de la retención no demuestra que la operación anterior fracasó. Un recurso borrado no demuestra que nunca se creó. A la inversa, parámetros idénticos pueden representar una segunda acción legítima. La identidad de una petición no debe absorber todas esas preguntas.

Un registro compacto y duradero de la operación puede vincularlas sin conservar eternamente todos los resultados. Puede contener alcance del solicitante, instrucción autorizada, compromiso sobre parámetros, aceptación, estado terminal y referencia al efecto. Debe tener acceso restringido y una retención justificada. Su función es conciliar una decisión, no acumular cargas sensibles por comodidad.

Esta propuesta de registro no es un campo obligatorio del borrador. Cada servicio puede realizarla de otro modo. El principio que importa es que la expiración del caché ordinario no destruya también el único camino para saber si una instrucción antigua todavía puede actuar.

Diseñar el comportamiento después del plazo

La documentación debería decir cuándo empieza la ventana, a qué solicitante y operación se aplica, cómo trata errores terminados y ejecuciones en curso, y qué sucede con una entrega tardía. Una fecha de eliminación aislada no explica cómo recuperar un resultado incierto.

Después del plazo, la petición vieja puede rechazarse, ponerse en espera revisable o contrastarse con una identidad de operación duradera. El cliente puede suspender la entrega automática, consultar estado y escalar la incertidumbre. Si se quiere producir otro efecto, debe aparecer una intención nueva explícita, no una recuperación disfrazada.

Un servicio puede publicar que el uso de una clave limpiada se procesa como nueva petición. El flujo cliente debe respetar esa frontera y dejar de describir el envío tardío como si siguiera cubierto por la garantía anterior. La semántica de transporte puede permitirlo; la autoridad de negocio necesita otra prueba.

Los botones humanos deben participar en esa distinción. «Reintentar» días después de un fallo puede tener un contrato diferente de la repetición automática segundos después. Si soporte genera un token nuevo para evitar un conflicto, puede cerrar el ticket a costa de abrir una segunda operación. La interfaz debería hacer visible la decisión que realmente se toma.

La memoria y la mutación deben coincidir

Recordar el token sin crear el recurso puede producir una falsa terminación. Crear el recurso sin recordar el token puede permitir repetirlo. El relato de AWS insiste en coordinar de forma atómica el registro y las mutaciones pertinentes.

Una transacción local, sin embargo, no siempre abarca una consecuencia posterior en otro servicio. El primer sistema puede haber confirmado su fila y el segundo haber actuado, aunque su acuse no regrese. El registro necesita saber qué fuente hace autoridad para cada efecto. Una terminación en la primera base no demuestra terminación de toda la cadena.

Las pruebas deben retrasar entregas más allá de la ventana, eliminar recursos antes de una repetición, cambiar parámetros y alcance del solicitante, y simular una terminación parcial en otro sistema. La condición de aceptación no es solo un código limpio. Es evitar un segundo efecto no autorizado y describir con veracidad lo que aún no se sabe.

Los caminos dormidos importan: una copia restaurada puede recuperar una instrucción ya ejecutada, un equipo puede reconectarse tarde y un export de soporte puede volver a entregar trabajo conciliado. No son excepciones extravagantes. Son la recuperación normal chocando con la duración de la memoria.

Fuentes

  1. Registro del borrador vencido
  2. Historial del borrador
  3. Revisión 07 en HTML
  4. Revisión 07 en texto
  5. XML de la revisión 07
  6. Mandato de HTTPAPI
  7. Documentos de HTTPAPI
  8. Repositorio oficial
  9. Problemas del proyecto
  10. RFC 9110: semántica HTTP
  11. RFC 9457: detalles de errores de API
  12. RFC 8941: campos estructurados
  13. RFC 9562: identificadores UUID
  14. RFC 9111: caché HTTP
  15. Stripe: peticiones idempotentes
  16. Stripe: errores de bajo nivel
  17. AWS: reintentos seguros con API idempotentes
  18. AWS: timeouts, reintentos y backoff
  19. Lu Heng: especificación inicial mínima y decisión local
  20. Lu Heng: el espejo de la política