Product3 Min. Lesezeit

Idempotency-Key: sichere Wiederholungen für PDF-Aufgaben

Sende Idempotency-Key auf POST unter /api/v1/. PDF123 puffert Erfolge 24 h im prozesslokalen Speicher und setzt Idempotency-Replayed: true statt doppelt zu laufen.

By the PDF123 team · Updated 2026-09-30
Idempotency-Key: sichere Wiederholungen für PDF-Aufgaben

Netzwerk-Timeouts und Wiederholungen im Client sind bei Multipart-Uploads von PDF normal. Ohne einen Idempotency-Key führt ein zweites POST dieselbe Zusammenführung, OCR oder Kompression erneut von vorn aus, wodurch Upload und Verarbeitungszeit verschwendet werden. Mit Idempotency-Key kann PDF123 stattdessen die erste erfolgreiche Antwort erneut ausgeben.

Was die Middleware tut

Die Middleware im Server pdfx-server gilt nur für verändernde Aufrufe: POST auf Pfade unter /api/v1/ (einschließlich /api/v1/pipeline). GET und andere Methoden laufen unverändert durch. Hat die Anfrage keinen Header Idempotency-Key (oder ist er nach dem Entfernen von Leerzeichen leer), läuft die Operation normal ohne Suche im Zwischenspeicher.

Ist der Header vorhanden:

  1. Der Speicher bildet den Schlüssel aus Principal und Key. Der Principal stammt aus X-API-KEY (als key:…), sonst aus Authorization (als auth:…), sonst aus dem Wort anon. Diese beiden Werte werden per SHA-256 zu einem Schlüssel der Zuordnung gehasht; der Inhalt der Anfrage ist nicht Teil des Schlüssels.
  2. Bei einem Treffer im Zwischenspeicher innerhalb von 24 Stunden gibt die Middleware den gespeicherten Status, den Content-Type, die Content-Disposition und den Inhalt zurück und setzt Idempotency-Replayed: true.
  3. Bei einem Fehlschlag läuft die Anfrage weiter. Nur erfolgreiche Antworten werden gepuffert und gespeichert (Antworten ohne Erfolg werden nicht für eine Wiederholung gespeichert).
  4. Die Inhalte der Antworten werden bis 100 MiB gepuffert, damit eine Wiederholung die Bytes der Datei erneut senden kann. Ein Inhalt, der nicht gepuffert werden kann, überspringt den Zwischenspeicher nicht still: Diese Anfrage liefert HTTP 500, eine zu große Antwort schlägt also fehl, statt ungecacht durchzugehen.

Fehlgeschlagene Aufgaben lassen sich gefahrlos mit dem selben Schlüssel wiederholen: Weil Fehler nicht gespeichert werden, kann der nächste Versuch gelingen und dann zum gespeicherten Ergebnis werden. Verwende einen Schlüssel nicht für eine andere Datei und andere Parameter erneut; der Zwischenspeicher hasht den Inhalt nicht, sondern nur Principal und Schlüssel. Zwei Aufrufer, die weder den API-Schlüssel noch die Autorisierung teilen, können nicht versehentlich kollidieren. Anonyme Aufrufer teilen den Principal anon und müssen deshalb unterschiedliche Schlüssel wählen.

Wie du den Schlüssel sendest

Wähle für jede logische Aufgabe eine stabile, undurchsichtige Zeichenfolge (eine UUID ist in Ordnung):

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

Anonyme Aufrufer und Aufrufer mit API-Schlüssel funktionieren beide. Abläufe, die erst ein Wasserzeichen und dann die Kompression verketten, sollten weiterhin einen Schlüssel pro HTTP-Anfrage senden, die du zusammenfassen willst, einschließlich jedes Schritts bei getrennten POST-Aufrufen, oder einen Schlüssel für einen einzelnen Aufruf von /api/v1/pipeline.

Einmalige Aufgaben im Browser auf Werkzeugseiten (Komprimieren, OCR, …) verlangen keinen erfundenen Schlüssel; der Header zählt für Clients, die wiederholen. Der veröffentlichte Skill unter /skills/pdf123.md zeigt aus demselben Grund einen Idempotency-Key in einem Beispiel für eine Pipeline.

Client-Muster, die funktionieren

  • Erzeuge den Schlüssel vor dem ersten POST und verwende ihn bei Wiederholungen nach einem Timeout für dieselbe logische Aufgabe erneut.
  • Prüfe bei Erfolg auf Idempotency-Replayed: true, wenn du wissen musst, ob diese Antwort aus dem Zwischenspeicher kam oder die Operation erneut ausgeführt wurde.
  • Ändere den Schlüssel, wenn sich Datei, Operation oder Parameter ändern, auch wenn der Principal gleich bleibt.
  • Bei /api/v1/pipeline deckt ein Schlüssel den ganzen POST der Pipeline ab und nicht jeden inneren Schritt.

Was die Wiederholung nicht ist

Die Wiederholung ist keine dauerhafte Warteschlange für Aufgaben. Der Speicher gehört zum Prozess (HashMap hinter einem Mutex) mit einer Gültigkeit von 24 Stunden. Nach dem Ablauf oder nach einem Neustart des Prozesses, der die Zuordnung im Speicher verwirft, führt derselbe Schlüssel die Operation erneut aus. Bereitstellungen mit mehreren Instanzen teilen diese Zuordnung nicht, solange kein gemeinsamer Speicher davorsteht; die heutige Middleware gehört jeweils zu einem Prozess.

Behandle Idempotency-Replayed: true als Beleg dafür, dass diese Antwort aus dem Zwischenspeicher kam, und nicht als dauerhaftes Verzeichnis. Es bedeutet nicht, dass die PDF erneut verarbeitet wurde, und verlängert die Gültigkeit nicht.

Mehr Details zur Oberfläche: Entwickler und Für KI-Agenten gebaut. Werkzeugseiten wie Komprimieren bleiben für einmalige Aufgaben im Browser verfügbar, ohne dass du Schlüssel erfinden musst.

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