Concepts
Idempotency
Make creating requests safe to retry with the Idempotency-Key header: what is stored, for how long, and the two ways a key is refused.
A network failure can leave you not knowing whether a request reached the server. For reads that does not matter; for a request that creates a pod or submits a job, sending it again could create a second one. Idempotency-Key removes the doubt.
How it works
Every creating POST accepts an Idempotency-Key header: any string of 1 to 255 characters, unique per operation you intend, such as a UUID.
- The first request with a key runs, and its response is stored with the key for 24 hours.
- A repeat with the same key and the same request gets the stored response, with the original status, and the header
Idempotent-Replayed: true. Nothing runs a second time. - If the first request failed, nothing is stored and the key can be used again.
Keys are scoped to the credential that sent them, so they never collide with another customer's or another key's.
KEY=$(cat /proc/sys/kernel/random/uuid) # any unique string up to 255 characters
BODY=$(jq -n --arg name "$NAME" '{name: $name, value: "example-value"}')
for attempt in 1 2; do
curl -sS --fail-with-body -D "headers.$attempt" "$API_BASE_URL/secrets" \
-H "$AUTH" -H "Content-Type: application/json" \
-H "Idempotency-Key: $KEY" -d "$BODY" | jq -r '"attempt '"$attempt"': \(.id)"'
grep -i '^idempotent-replayed' "headers.$attempt" || echo "(first answer)"
doneWhen a key is refused
- The same key with a different request (another body, path or project) is refused with
422, typeidempotency_errorand codeidempotency_key_reused. - A repeat that arrives while the first is still running gets
409with codeidempotency_in_progress. Wait and retry; it will then get the stored response.
try {
await client.secrets.create({ name, value: 'a different value' }, { idempotencyKey: key });
throw new Error('expected the reused key to be refused');
} catch (err) {
if (err instanceof IdempotencyError)
console.log('refused:', err.code); // idempotency_key_reused
else throw err;
}In the SDKs
The SDKs send a fresh key with every creating call and keep it across their own retries. Pass your own key (idempotencyKey in TypeScript, request_options={"idempotency_key": …} in Python) when the retry may come from another process, such as a job runner that restarts: store the key with the work item before you send the request.
For uploads (POST /v1/files) the stored identity is the file content: a retry with the same key, purpose, file name and bytes returns the original file.