Idempotency

Safe retries

A network can fail after the API has done the work and before you read the answer. To send the call again without doing the work twice, send an Idempotency-Key header of 1 to 255 visible ASCII characters, such as a random UUID, on the calls that create something: starting a run, saving a document and creating a webhook endpoint.

• The same key with the same request returns the first answer, with Idempotent-Replayed: true. The work is not done again and nothing more is counted.
• The same key with a different body or on a different route is refused with idempotency_key_reused (422).
• A second request while the first is still running is refused with idempotency_in_progress (409). Wait a moment and send it again.
• Only a success is kept. A call that failed releases its key, so the same key can be sent again after you fix the cause.
• Keys are kept for 24 hours and belong to the account, so two accounts may use the same text.

curl -X POST https://api.pdfloft.com/v1/documents \
  -H "Authorization: Bearer $PDFLOFT_API_KEY" \
  -H "Idempotency-Key: 8d6e3b3e-7c1f-4a37-9b85-0f4d1c7e2a11" \
  -H "Content-Type: application/json" \
  -d '{"source":{"jobId":"cm3x8k2f10001","index":0},"name":"Protected.pdf"}'

Reads and deletes are already safe to repeat and ignore the header.