Idempotency

A command takes an Idempotency-Key, so a retry after a timeout returns the stored result and changes nothing.

Commands are the requests that create something; in Ciresk CI that is submitting a job, committing blobs, registering a repository or a worker, enrolling a worker, creating a webhook. Each requires an Idempotency-Key header; the reference marks them. Reuse the key when you retry the same request.

Ciresk CI example

curl -s -X POST "$CIRESK_API/v1/ci/jobs" \
  -H "Authorization: Bearer $CIRESK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: nightly-check-2026-10-20" \
  -d @job.json

Rules

Derive keys from your own records (nightly-check-2026-10-20), not a random value per attempt.
Use 1 to 255 printable ASCII characters.
A command without the header is 400 idempotency_key_required; an empty or too long key is 400 invalid_idempotency_key.
The same key with a different body is 422 idempotency_key_reused. Use a new key for a new request; reuse a key only for a retry of the same one.
A retry after 429, 500 or 503 carries the same key, so nothing runs twice.

Deduplication of jobs (Ciresk CI)

In Ciresk CI, job submission is deduplicated on top of the idempotency key: an identical job (same repository, base commit, diff, kind, targets, full and toolchains) that is already queued or running comes back with 200, deduplicated: true and deduplicated_from (the first submitter's actor, never its credential), and the budget is charged once. no_dedup: true opts out of that; nothing opts out of the idempotency key. See How it works.