Product4 min de lecture

Idempotency-Key : des reprises sûres pour les tâches PDF

Envoyez Idempotency-Key sur les POST /api/v1/. PDF123 met 24 h les réponses en mémoire du processus ; un rejeu ne relance rien et renvoie Idempotency-Replayed: true.

By the PDF123 team · Updated 2026-09-30
Idempotency-Key : des reprises sûres pour les tâches PDF

Les délais d’attente réseau et les nouvelles tentatives côté client sont normaux pour les téléversements PDF en multipart. Sans clé d’idempotence, un second POST relance la même fusion, le même OCR ou la même compression depuis le début, ce qui duplique le téléversement et le temps de traitement. Avec Idempotency-Key, PDF123 peut rejouer la première réponse réussie.

Ce que fait le middleware

Le middleware du serveur pdfx-server ne s’applique qu’aux appels mutatifs : les POST vers des chemins sous /api/v1/ (y compris /api/v1/pipeline). Les GET et les autres méthodes passent sans changement. Si la requête n’a pas d’en-tête Idempotency-Key (ou que celui-ci est vide après suppression des espaces), l’opération s’exécute normalement, sans consultation du cache.

Quand l’en-tête est présent :

  1. Le magasin indexe l’entrée par principal + clé. Le principal provient de X-API-KEY (sous la forme key:…), sinon de Authorization (auth:…), sinon du littéral anon. Ces deux valeurs sont hachées (SHA-256) pour former la clé de la table ; le corps de la requête n’entre pas dans la clé.
  2. En cas de correspondance en cache dans les 24 heures, le middleware renvoie le statut, le type de contenu, le nom de fichier et le corps enregistrés, et ajoute Idempotency-Replayed: true.
  3. En l’absence de correspondance, la requête se poursuit. Seules les réponses réussies sont conservées en mémoire et stockées (les réponses non réussies ne sont pas gardées pour rejeu).
  4. Les corps de réponse sont mis en tampon jusqu’à 100 MiB, pour qu’un rejeu puisse renvoyer les octets du fichier. Un corps qui ne peut pas être mis en tampon n’ignore pas le cache en silence : cette requête renvoie HTTP 500, donc une réponse au-delà de la limite échoue au lieu de passer sans cache.

Une tâche échouée peut être relancée sans risque avec la même clé : les échecs n’étant pas stockés, la tentative suivante peut réussir puis devenir le résultat en cache. Ne réutilisez pas une clé pour un autre fichier ou d’autres paramètres ; le cache ne hache pas le corps, seulement le principal et la clé. Deux appelants qui ne partagent ni clé API ni en-tête Authorization ne peuvent pas se heurter par accident. Les appelants anonymes partagent en revanche le principal anon : ils doivent donc choisir des clés distinctes.

Comment l’envoyer

Choisissez une chaîne opaque et stable par tâche logique (un UUID convient) :

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

Les appelants anonymes comme ceux qui utilisent une clé API sont acceptés. Une chaîne qui enchaîne filigrane puis compression doit tout de même envoyer une clé par requête HTTP à dédupliquer, y compris pour chaque étape si vous les envoyez séparément, ou une seule clé pour un appel unique à /api/v1/pipeline.

Les usages ponctuels dans le navigateur (Compresser, OCR, …) ne vous obligent pas à inventer une clé ; l’en-tête compte pour les clients qui relancent. La compétence publiée à /skills/pdf123.md illustre un Idempotency-Key sur un exemple de pipeline, pour la même raison.

Les bonnes pratiques côté client

  • Générez la clé avant le premier POST ; réutilisez-la pour les nouvelles tentatives après expiration du délai, sur la même tâche logique.
  • En cas de succès, vérifiez Idempotency-Replayed: true si vous voulez savoir si la réponse vient du cache ou d’une nouvelle exécution.
  • Changez de clé dès que le fichier, l’opération ou les paramètres changent, même si le principal reste identique.
  • Pour /api/v1/pipeline, une clé couvre l’ensemble du POST, et non chaque étape interne.

Ce que le rejeu n’est pas

Le rejeu n’est pas une file de tâches durable. Le magasin est local au processus (une HashMap derrière un mutex) avec une durée de vie de 24 heures. Passé ce délai, ou après un redémarrage qui vide la table en mémoire, la même clé relance l’opération. Les déploiements à plusieurs instances ne partagent pas cette table, sauf à placer un magasin partagé devant ; le middleware actuel est propre à chaque processus.

Voyez Idempotency-Replayed: true comme la preuve que la réponse vient du cache, non comme un registre permanent. Cela ne signifie pas que le PDF a été retraité et ne prolonge pas la durée de vie.

Pour plus de détails : Développeurs et Conçu pour les agents IA. Les pages d’outils comme Compresser restent disponibles pour les tâches ponctuelles dans le navigateur, sans inventer de clé.

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