Skip to main content

The problem retries create

A POST 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 the Idempotency-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.
The first call reserves the key and runs the job. Each subsequent call with that key lands on the same reservation and returns the stored response without re-running inference. The key only earns its keep once you actually retry.

Rules that govern a reservation

(workspace, idempotency key)
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.
body not compared
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.
key not consumed
Any 4xx raised before the reservation is written leaves the key unreserved. You can fix the body and retry under the same key.
not a frozen copy
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.