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

# Idempotency

> Retry a Bizzy API write safely by sending an Idempotency-Key header

<Badge color="green">New</Badge>

Send an `Idempotency-Key` header on any `POST` request that takes a JSON body to
make it safe to retry. If the first attempt already succeeded, the retry returns
that original response instead of creating a second record or sending a second
message. File uploads are the exception — they take form data, and the header
has no effect there.

```bash theme={null}
curl -X POST "https://api.bizzyco.ai/v1/contacts" \
  -H "Authorization: Bearer $BIZZY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f8c2b1a-4d3e-4a6b-8c1d-2e3f4a5b6c7d" \
  -d '{"firstName":"Ada","lastName":"Lovelace"}'
```

Generate a unique value per operation — a UUID is a good choice. The header is
optional: a request without it behaves exactly as it always has.

## Retrying

Send the identical request — same endpoint, same body — with the same key. The
replayed response carries an `Idempotency-Replay: true` header so you can tell
it apart from a fresh one.

Use a new key whenever you mean to perform a new operation, even a similar one.
Reusing a key with a changed body is rejected rather than treated as a retry, so
a key is bound to exactly one request.

Keys are scoped to your organization and last 24 hours. After that the same
value can be used again for a new operation.

## While a request is still running

If you retry before the original request has finished, the retry returns `409`
and the original keeps running. Wait, then retry again to collect the result.

A request that fails releases its key immediately, so you can retry it with the
same key. When an error tells you to use a new key, use one — retrying with the
original returns the failed attempt instead of starting a new one.

## Errors

| Code                        | Status | Description                                         |
| --------------------------- | ------ | --------------------------------------------------- |
| `IDEMPOTENCY_KEY_IN_FLIGHT` | 409    | The original request with this key is still running |
| `IDEMPOTENCY_KEY_REUSED`    | 422    | This key was already used for a different request   |

See [Errors](/api-reference/errors) for the full catalog.

## Domain registration and renewal

Registering a domain (`POST /v1/domain-registrations`) and renewing one
(`POST /v1/domains/{id}/registration/renew`) move money, so the header is
required there. Omitting it returns `400`. See
[Register a Domain via the API](/api-reference/domain-registration).