# Idempotency

Retry safely: the same Idempotency-Key never creates a second post.


Networks fail and AI agents retry. If a "create post" request times out, you cannot tell whether the post was created. Send an `Idempotency-Key` header on `POST /posts` and `POST /media` so retrying is safe:

```bash
curl -X POST https://creatorhyve.com/api/v1/developer/posts \
  -H "Authorization: Bearer $CH_KEY" \
  -H "Idempotency-Key: 6f1a2b0c-launch-announcement" \
  -H "Content-Type: application/json" \
  -d '{ "caption": "We launched!", "platforms": ["x"], "scheduledDatetime": "2030-01-15T09:00:00Z" }'
```

| Situation | Result |
|---|---|
| First request with this key | Processed normally. |
| Same key, same body | The first response is replayed, with the header `Idempotent-Replayed: true`. |
| Same key, different body | `422` with `idempotency_key_reuse`. |
| Same key while the first request is still running | `409` with `idempotency_in_progress`; retry in a couple of seconds. |
| First request failed with a 5xx error | Nothing is stored; retrying with the same key runs it again. |

Use any unique string up to 200 characters, such as a UUID or an id from your own system. Keys are remembered for 24 hours.