PDFHQ-logo

Documenten

DocumentatieAan de slag

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.

Server-side API-sleutels Ondertekende opslagupload

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.

Taak maken met retry-sleutel
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.

PDFHQ-logo

PDF-tools en documentintelligentie. Bereid, begrijp en werk met uw documenten.

© 2026 PDFHQ. Alle rechten voorbehouden.