# Idempotency

Retry a write safely with an Idempotency-Key, and know when a key is required.



A network error leaves you not knowing whether a write happened. Send an `Idempotency-Key` header
with any `POST`, `PUT`, `PATCH` or `DELETE`, and a retry with the same key and the same body gets
the first answer back instead of doing the work twice.

```bash
curl -X POST https://api-hq.aiworkforceone.com/v1/sessions/sess_…/messages \
  -H "Authorization: Bearer $HQ_API_KEY" \
  -H "Idempotency-Key: 6c1f2b0e-run-42" \
  -H "Content-Type: application/json" \
  -d '{"content":[{"type":"text","text":"Summarise the open pull requests"}]}'
```

* Use a new key for each new action, for example a UUID. Up to 255 printable ASCII characters.
* A key belongs to the key that sent it and lasts 24 hours.
* A replayed answer carries `Idempotent-Replayed: true`, the same status and body, and the same
  `Location` header for a create. A retried `DELETE` answers its first `204` again, even though
  the object is gone.
* The same key with a different request (another body, query, path or route) is refused:
  `422 idempotency_key_reused`.
* While the first request is still running, a retry is refused with `409 idempotency_in_progress`
  and `Retry-After`. Wait, then retry with the same key.
* Answers that say "try again" are not stored, so a retry runs for real: `409` conflicts, `421`
  misdirected, `429` rate limits and `5xx` errors.

## Where a key is required [#where-a-key-is-required]

These writes start something you cannot take back, so they refuse a request without a key
(`400 invalid_request`, field `Idempotency-Key`):

| Request                                                            | Why                                                     |
| ------------------------------------------------------------------ | ------------------------------------------------------- |
| `POST /teams/{team_id}/sessions`                                   | Starts a session.                                       |
| `POST /sessions/{session_id}/messages`                             | Types into the session. A prompt is typed at most once. |
| `POST /sessions/{session_id}/actions`                              | Answers a question or a permission request.             |
| `POST /teams/{team_id}/computer/start`, `stop`, `update`, `resize` | Changes the machine.                                    |
| `POST /schedules/{schedule_id}/runs`                               | Runs a schedule now.                                    |

Everywhere else the key is optional and works the same way.

## A secret is never replayed [#a-secret-is-never-replayed]

`POST /secrets` and the other secret writes store their answer for replay like any other write. The
answer never contains the secret's value, so the stored copy does not either. What is stored about
the request itself is a keyed digest, never the value or a plain hash of it.

A webhook endpoint's signing secret is shown once, in the answer to `POST /webhook_endpoints` and
`POST /webhook_endpoints/{webhook_endpoint_id}/rotate_secret`, and it is not stored for a replay. A
retry with the same key answers the same endpoint without `secret` and with
`secret_omitted: true`. If you lost the first answer, roll the secret to get a new one.
