PDFHQ-Logo

Dokumente

DokumentationErste Schritte

Idempotenz und Wiederholungssicherheit

Sichere Wiederholung der Dokumentaufgabenerstellung über Netzwerk-Timeouts mit projektbezogenen Idempotency-Key-Headern und Unterscheidung von bezahlten Prozessen und Provider-Dispatch.

Server-seitige API-Schlüssel Signierte Speicher-Uploads

Wiedergabesichere Aufgabenerstellung#

POST /v1/tasks akzeptiert optional Idempotency-Key (8–128 ASCII-Buchstaben, Ziffern, Punkte, Unterstriche, Doppelpunkte oder Bindestriche; beginnt mit einem Buchstaben oder einer Ziffer). Das Wiederholen eines Schlüssels für dasselbe HQTools-Konto und API-Projekt gibt die vorhandene Aufgabe zurück. Die Wiederverwendung desselben Schlüssels für ein anderes Tool gibt zurück 409 IDEMPOTENCY_KEY_REUSED.

Erstelle Aufgabe mit Wiederholungsschlüssel
curl -q --fail-with-body -X POST 'https://api.pdfhq.io/v1/tasks' \
  -H 'x-api-key: YOUR_SERVER_SIDE_API_KEY' \
  -H 'Idempotency-Key: job-20261025-00001' \
  -H 'Content-Type: application/json' \
  -d '{"tool":"compress"}'

Die zurückgegebene Aufgaben-ID ist über Wiederholungen hinweg stabil. Schlüssel sind auf ein Konto und ein API-Projekt beschränkt und bleiben mit der Aufgabe verknüpft, bis der zugrunde liegende Datensatz gelöscht wird. Erstelle einen neuen Schlüssel für eine neue Aufgabe.

Unterschiedliche Wiederholungsregeln für verschiedene Ressourcen#

Task-Erstellung: Wiederholung mit demselben Idempotency-Key nach einer Netzwerkunterbrechung. Task-Verarbeitung: Die feste Task-ID bietet bereits Backend-Job-/Kreditidempotenz für identische Optionen; überprüfe ihren Status, bevor du es erneut versuchst. KI-Jobs: Verwende ein neues benutzerbestätigtes Zitat und einen stabilen Idempotency-Key, wie vom KI-Endpunkt unterstützt. eSignatur senden: eine unsichere Anbieterantwort erfordert Umschlagabstimmung; sende nicht blind eine Signaturanfrage erneut.

Signierte S3-Uploads verwenden kurzlebige POST-Formularrichtlinien. Sende nicht x-api-key oder Idempotency-Key zu S3. Speicher-Uploads und Kostenvoranschläge belasten selbst keine Credits; die Verarbeitung tut es.

PDFHQ-Logo

PDF-Werkzeuge und Dokumentenanalyse. Dokumente vorbereiten, verstehen und bearbeiten.

© 2026 PDFHQ. Alle Rechte vorbehalten.