Skip to navigation

Idempotency

Retry a call without a second job. The key lives for 24 hours.
View as Markdown

Send an Idempotency-Key header on POST /v2/{capability}. A retry with the same key and the same body returns the first job. The API starts no second job.

curl -s -X POST "https://$CRK_SLUG.cloudraker.run/v2/parse" \
-H "Authorization: Bearer $CRK_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: inv-2026-11-07-0042" \
-d '{ "file": { "url": "https://files.example.com/invoice-0042.pdf" } }'

Rules

RuleValue
Key format1 to 255 visible ASCII characters. Another value gives 400 invalid_request.
Lifetime24 hours from the first request.
ScopePer credential. Another credential with the same key creates its own job.
FingerprintThe method, the path and the body. The key order and the white space of the JSON do not count.
Not includedPrefer and ?wait. A retry can change them.

Answers

CaseAnswer
First requestThe job. The API creates it.
Same key and same bodyThe first job, with the header idempotent-replayed: true.
Same key and another body409 idempotency_key_reused. Use a new key for a new request.

A replay waits for the first job under the same Prefer rules. A replay of a job with stale signed URLs gets new URLs.

If the API fails a job with 503 capability_unavailable, it deletes the claim of the key. A retry with the same key then creates a new job.

Retry a failed call

Use the same Idempotency-Key after a network error or a 500. The retry gets the first job and starts no second job. Use a new key when you want a new job.