Safe retries & idempotency

An idempotency key lets you retry a write without applying the same operation twice.

Idempotent writes

Every published POST and PATCH customer API mutation requires an Idempotency-Key header. Use a new value of 8 to 128 characters containing only letters, digits, periods (.), underscores (_), colons (:) or hyphens (-). Do not include spaces.

Retry with the same API credential, method, endpoint, key and body to retrieve the original successful result. Reusing that key for a different operation, resource or body with the same credential returns 409 Conflict.

Resume downloads and ordinary read requests do not require an idempotency key. Upload-plan endpoints are not currently published.

Keys are scoped to an API credential. Switching to a new or rotated credential does not replay a receipt created with the previous credential and can repeat the operation. Reconcile an uncertain write before changing credentials.

Example header

Idempotency-Key: cvviz-create-job-20260911-001

Generate your own unique value for each logical operation. Do not reuse this documentation example across unrelated requests.

If a request times out

1. Keep the original API credential, method, URL, body and idempotency key.

2. Retry with bounded exponential backoff and jitter.

3. For 429 or 503, respect Retry-After when supplied.

4. If you receive 409, read the details. Do not generate a new key merely to work around a conflict; that can create a second operation.

A successful creation replay returns the original creation result, not a fresh view of the job. Read the job to obtain its current state. To change a draft to active later, use the status endpoint with a new key.

Reads and usage

GET requests do not need an idempotency key. Retry transient failures with a bounded backoff; do not repeatedly retry 400, 401 or 403 without correcting the cause. Each admitted retry still counts toward metered usage, even if its write result is replayed.