Product4 min de lectura

Idempotency-Key: reintentos seguros para trabajos PDF

Envía Idempotency-Key en POST a /api/v1/: PDF123 cachea 24 h respuestas correctas en memoria del proceso; el reenvío no se ejecuta y da Idempotency-Replayed: true.

By the PDF123 team · Updated 2026-09-30
Idempotency-Key: reintentos seguros para trabajos PDF

Los tiempos de espera de red y los reintentos del cliente son normales en las subidas multipart de PDF. Sin una clave de idempotencia, un segundo POST puede volver a ejecutar la misma combinación, el mismo OCR o la misma compresión y duplicar la subida y el tiempo de proceso. Con Idempotency-Key, PDF123 puede reenviar la primera respuesta correcta.

Qué hace el middleware

El middleware del servidor, en pdfx-server, solo se aplica a las llamadas que modifican datos: los POST a rutas bajo /api/v1/ (incluido /api/v1/pipeline). Los GET y los demás métodos pasan sin cambios. Si la petición no trae la cabecera Idempotency-Key (o queda vacía al recortar espacios), la op se ejecuta con normalidad y no se consulta ninguna caché.

Cuando la cabecera está presente:

  1. El almacén indexa la entrada por principal + clave. El principal se deriva de X-API-KEY (como key:…); si no, de Authorization (como auth:…); y si no, del literal anon. Esos dos valores se convierten en la clave del mapa mediante un hash SHA-256; el cuerpo de la petición no forma parte de la clave.
  2. Si hay acierto en la caché dentro de las 24 horas, el middleware devuelve el estado, el tipo de contenido, la disposición de contenido y el cuerpo guardados, y añade Idempotency-Replayed: true.
  3. Si no hay acierto, la petición continúa. Solo se almacenan las respuestas correctas (las incorrectas no se guardan para reenvío).
  4. Los cuerpos de respuesta se almacenan hasta 100 MiB para que un reenvío pueda devolver los bytes del archivo. Un cuerpo que no se pueda almacenar no se salta la caché en silencio: esa petición devuelve HTTP 500, así que una respuesta por encima del límite falla en vez de pasar sin caché.

Los trabajos fallidos se pueden reintentar con la misma clave sin problema: como los fallos no se guardan, el siguiente intento puede salir bien y pasar a ser el resultado en caché. No reutilices una clave para un archivo o unos parámetros distintos: la caché no aplica hash al cuerpo, solo al principal y a la clave. Dos llamadores que no compartan ni clave de API ni Authorization no pueden coincidir por accidente; los llamadores anónimos comparten el principal anon, así que deben elegir claves distintas.

Cómo enviarla

Elige una cadena opaca y estable para cada tarea lógica (un UUID sirve):

curl -X POST "https://pdf123.xyz/api/v1/misc/compress-pdf" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -F "[email protected]"

Funcionan tanto los llamadores anónimos como los que usan clave de API. Los pipelines que encadenan marca de agua y luego compresión deben seguir enviando una clave por cada petición HTTP que quieras deduplicar: una por paso si los envías por separado, o una sola para una llamada a /api/v1/pipeline.

Las tareas puntuales del navegador en las páginas de herramienta (Comprimir, OCR y demás) no te obligan a inventar una clave; la cabecera importa para los clientes que reintentan. La skill publicada en /skills/pdf123.md muestra un Idempotency-Key en un ejemplo de pipeline por ese mismo motivo.

Patrones de cliente que funcionan

  • Genera la clave antes del primer POST y reutilízala en los reintentos por tiempo de espera de esa misma tarea lógica.
  • Cuando la respuesta sea correcta, comprueba Idempotency-Replayed: true si necesitas saber si volvió a ejecutar la operación o vino de la caché.
  • Cambia la clave cuando cambien el archivo, la op o los parámetros, aunque el principal siga siendo el mismo.
  • Para /api/v1/pipeline, una sola clave cubre todo el POST del pipeline, no cada paso interno.

Qué no es un reenvío

Un reenvío no es una cola de tareas duradera. El almacén es local al proceso (un HashMap protegido por un mutex) con un TTL de 24 horas. Una vez caduca, o después de un reinicio del proceso que vacía el mapa en memoria, la misma clave vuelve a ejecutar la op. Los despliegues con varias instancias no comparten ese mapa salvo que pongas delante un almacén compartido: el middleware actual es por proceso.

Toma Idempotency-Replayed: true como prueba de que esta respuesta vino de la caché, no como un registro permanente. No significa que el PDF se haya reprocesado y no amplía el TTL.

Para más detalle de la superficie, consulta Desarrolladores y Hecho para agentes de IA. Las páginas de herramienta como Comprimir siguen disponibles para tareas puntuales en el navegador sin inventar claves.

Open tool
Process in the browser — no watermark, files removed after the job.
Open tool