Idempotentie en herhalingsveiligheid
Voer documenttaakmaking veilig opnieuw uit over netwerktime-outs met behulp van project-scoped Idempotency-Key-headers, en onderscheid deze van betaalde processen en providerverzending.
Replay-veilige taakmaking#
POST /v1/tasks accepteert een optioneel Idempotency-Key (8–128 ASCII-letters, cijfers, punten, underscores, dubbele punten of koppeltekens; begint met een letter of cijfer). Het herhalen van een sleutel voor dezelfde HQTools-account en API-project retourneert de bestaande taak. Het hergebruiken van dezelfde sleutel voor een ander hulpmiddel retourneert 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"}'De geretourneerde taak-ID is stabiel bij herhaalde pogingen. Sleutels zijn bereikt voor een account en API-project en blijven aan de taak gekoppeld totdat de onderliggende record wordt verwijderd. Maak een nieuwe sleutel voor een nieuwe taak.
Verschillende herhaalpogingsregels voor verschillende resources#
Taak aanmaken: opnieuw afspelen met dezelfde Idempotency-Key na een netwerkonderbreking. Taakverwerking: de vaste taak-ID biedt al backend job/credit-idempotentie voor identieke opties; controleer de status voordat u het opnieuw probeert. AI-taken: gebruik een vers door de gebruiker goedgekeurd aanhalingsteken en stabiele Idempotency-Key zoals ondersteund door het AI-eindpunt. eSignature verzenden: een onzekere providerrespons vereist envelopverzoening; stuur een handtekeningsverzoek niet blindelings opnieuw in.
Ondertekende S3-uploads gebruiken kortdurende POST-formulierbeleid. Niet verzenden x-api-key of Idempotency-Key naar S3. Opslagupload en prijsramingen brengen zelf geen credits in rekening; verwerking wel.
