> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnichar.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Retry requests safely with Idempotency-Key

> Send an Idempotency-Key header on any POST so a retry after a timeout returns the original answer for 24 hours instead of creating a second character.

Networks drop answers. If a `POST /v1/chars` times out, you can't tell whether the character was created. Send an `Idempotency-Key` header and retry with the same key: you get the original answer, and nothing is created twice.

```bash theme={null}
curl -s -X POST https://api.omnichar.org/v1/chars \
  -H "Authorization: Bearer $OMNICHAR_API_KEY" \
  -H "Idempotency-Key: create-subject-001" \
  -H "Content-Type: application/json" \
  -d '{ "subject_id": "subject-001", "references": { "face": ["..."] } }'
```

Every POST accepts the header. The rules:

* A key is 8 to 255 visible ASCII characters. A UUID or your own record id works well.
* Keys belong to the API key that sent them, and are kept for 24 hours.
* The same key with the same body, within 24 hours, returns the first status and body again with the header `Idempotent-Replayed: true`.
* The same key with a different body is refused with `422`. Bodies are compared by content, so key order does not matter.
* If the first request is still running, a repeat gets `409`. Wait and retry.
* A `5xx` answer is not stored, so retrying with the same key runs the request again.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.