Build with the API
Retry safely with an Idempotency-Key
A network can fail after your request was sent and before you saw the answer. If you send it again, you want the first answer back, not a second run and a second charge. Send an Idempotency-Key header and that is what happens.
curl https://sven.swedishembedded.com/v1/chat/completions \
-H "Authorization: Bearer $SVEN_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f0c5e2a-9a1b-4c1e-9b0e-2d7f5b1a8c34" \
-d '{"model": "MODEL_ID", "messages": [{"role": "user", "content": "Hello"}]}'
The key#
A key is 1 to 255 printable characters with no spaces. A random UUID is a good choice. Make it once for each thing you want done, and send the same one with every retry of it. A new action gets a new key.
What happens on a retry#
A retry is the same value, sent with the same API key and the same request body.
| The first call | The retry gets |
|---|---|
| Finished | Its stored answer, in the same shape, without running again and without a second charge. A streamed call is replayed as a stream. |
| Streamed, and broke after the model reported its usage | The output it delivered before it broke, as a stream, ending with the same error. It is what you were charged for, and it is not charged again. |
| Still running | 409 (idempotency_error). Wait a moment and retry. |
| Finished, but its answer is no longer stored | 409 (idempotency_error). The call was charged once; send a new key to run it again. |
Another API key, or another body, under the same value is a call of its own. A key therefore can never return somebody else's answer.
How long answers are kept#
A stored answer is kept for 24 hours. A streamed answer is kept whatever its length. Other answers larger than 1 MiB, such as a big batch of embeddings or several images, are not kept: a retry of one of those is answered 409 once the first call has finished, and it is not charged again.
Where it works#
Every route that does work accepts it: chat completions, messages, embeddings, images, speech to text and search. It makes no difference on GET /v1/models.
When you need it#
Send one whenever a duplicate would cost money or have an effect, which is any call you retry automatically. Calls you make by hand, once, do not need it.