# Idempotent requests

Networks fail. With an `Idempotency-Key` you can safely send a writing request again: mint runs it at most once
and returns the stored response for every repeat.

Writing `POST` requests require an `Idempotency-Key` header (1–128 visible ASCII characters, for example a UUID);
`PATCH` accepts it optionally. `POST /films` accepts it optionally when the body has a `video_key` (the version identity
then protects against duplicates); without `video_key` it is required (`400 idempotency_key_required`).
`POST /films/{id}/cancel` accepts it optionally. Repeating a request with the same key and the same body returns the stored response
with `Idempotent-Replayed: true` and changes nothing. This also applies to error responses (`400`, `404`,
`409`): their body is replayed unchanged, so `error.request_id` names the original request, while
`X-Request-Id` names the current one. Temporary rejections are not stored (`409 feedback_busy`, `409 film_busy`, `409 preview_in_progress`, `409 storyboard_not_ready`, `402 insufficient_credits`, `409 feedback_queue_full`):
a retry with the same key runs again once the reason is gone. The same key with a different request returns
`422 idempotency_mismatch`; while the first request is still running you get `409 idempotency_in_progress` with
`Retry-After`. Keys are kept per API access for 24 hours by default; the operator of a mint server can set
1–72 hours. `GET /me` shows the current value in `idempotency_key_ttl_hours`.

### Good practice

- Create a new random key (for example a UUID v4) for every new action, and reuse it only for retries of that action.
- Store the key together with your own job, so a retry after a crash uses the same key.
- For films, prefer `video_key` + `version` (see [Film versions](/api/film-versions)): they protect against duplicates
  for as long as the film exists, not only for 24 hours.

```sh Request with Idempotency-Key
curl -X POST https://api.cream-ai.de/api/v1/categories \
  -H "Authorization: Bearer $MINT_API_KEY" \
  -H "Idempotency-Key: 9b1d3c5e-7f2a-4c6e-8a0b-2d4f6a8c0e1b" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Marketing", "external_key": "MKT" }'
```

```http Repeated request
HTTP/1.1 201 Created
Idempotent-Replayed: true
X-Request-Id: req_0c3e5a7b9d1f2e4a6c8b0d2f4e6a8c1b
```