The problem retries create
APOST that times out or returns a 5xx leaves you guessing. The server may have received the request and run the inference, or it may not have. Retrying blindly risks running and billing the same job twice. Not retrying risks dropping a job that never actually completed.
An idempotency key removes the guesswork. You attach a key to the first attempt, Valar stores the response under that key, and every later attempt with the same key returns that stored response instead of running inference again. Retrying becomes safe across flaky networks, timeouts, and ambiguous 5xx responses.
How it works
Send the key in theIdempotency-Key request header. Use one key per logical request (a UUID or any unique string up to 255 characters) and send the same key on the first attempt and every retry.
Rules that govern a reservation
A reservation is identified by the workspace that owns your API key and the idempotency key. Every API key in the same workspace shares one namespace: the same idempotency key sent with two different API keys from that workspace lands on the same reservation. Rotating API keys therefore won’t break replay. Keys in different workspaces never collide.
Valar does not compare a retry’s body with the original. Any later request with a reserved key returns the stored response, even when its body is different. This lets you poll a long-running request by resending its key with a minimal body. It also means a changed request needs a new key: reusing a key after you change the request returns the earlier response, not an error.
Any
4xx raised before the reservation is written leaves the key unreserved. You can fix the body and retry under the same key.A replay returns the current state of the underlying response record. For background requests the
status tracks the task’s latest transition, such as queued → in_progress → completed.Deciding when to retry
Reach for the same idempotency key whenever the outcome is ambiguous. Don’t retry when the work genuinely failed.See also
- Sending Requests at Scale - the batch and background workflows where idempotent retries pay off most.
- Webhooks - pair idempotent retries with webhook delivery so a client can re-drive submission without triggering another inference run.