Guides
Idempotency
Make creating an execution safe to retry.
Idempotency lets you retry a request to create an execution without creating a duplicate run.
If your request times out, retry it with the same Idempotency-Key and request body. If WOOL already created
an execution for that key, it returns the existing execution. Otherwise, it creates one.
How it works
Send Idempotency-Key on POST /v1/applications/{id}/executions. The key is 1–255 characters and is scoped to
the connection.
| Situation | Result |
|---|---|
| Same key, same body | The original execution, whatever its status. |
| Same key, different body | 409 IDEMPOTENCY_KEY_REUSED. |
| No key | A new execution every time. |
The body is compared as prompt, start_url, and output_schema after normalizing, so key order and
whitespace don't matter.
The pattern
- Generate a UUID for the run you intend to start.
- Store it with the request before you send anything.
- Send the request with that key.
- On any retry of that request, reuse the key.
If your process crashes after sending the request, retry with the key and request body you stored in step 2. WOOL returns the existing execution if the first request created one.
Next steps
Handling failures explains when a retry should reuse the key and when it should be a new run.