Retrying a render with the same idempotency key, within the same project, returns the original
render instead of creating a duplicate. This makes at-least-once delivery — an offline-first app
that resubmits a sign-off on reconnect — safe.
Supplying a key
Send an Idempotency-Key header (preferred), or a jobId in the body. If both are present
the header wins. Renders with no key are never deduplicated.
Behavior
- First call with a key creates the render and returns
202.
- Repeat call with the same key returns the existing render with its current state
(
status, downloadUrl, …) and 200. So a retry after completion returns the finished render
and its download URL.
- Scope is per project — the same key in two different projects creates two renders.
- A concurrent double-submit races safely: a unique constraint ensures only one render is created;
the loser receives the winner’s render.
Use a key derived from the business event, not a random UUID per attempt — e.g.
handover-{bookingCode}-{checkin|checkout}. The whole point is that all retries of the same
event share one key.
Important: failures are not retried by the same key
Idempotency returns the stored render regardless of its status — including failed. Retrying a
failed render with the same key returns the failed render; it does not trigger a fresh attempt.
To deliberately re-render after a failure, submit with a new idempotency key.
200 (idempotent replay) vs 202 (newly queued) lets you tell the two apart in client code if
you need to.