Idempotenz und Wiederholungssicherheit
Sichere Wiederholung der Dokumentaufgabenerstellung über Netzwerk-Timeouts mit projektbezogenen Idempotency-Key-Headern und Unterscheidung von bezahlten Prozessen und Provider-Dispatch.
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.
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.
