# Retrying safely with idempotency keys

> Send an Idempotency-Key with a POST so a retry after a timeout never creates the same task, appointment or deal twice.

Networks fail. If a `POST` times out, you can't tell whether it ran. An `Idempotency-Key` makes the retry safe: send the same key again, and the action happens once.

```bash
curl -X POST https://workspace.brokerandagent.com/api/public/v1/tasks \
  -H "Authorization: Bearer bak_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f1c2b8e-6d0a-4a1e-9c57-2b1d3e4f5a60" \
  -d '{ "title": "Call Dana back", "contactId": "ct_…" }'
```

## How it works

- Make up one key per logical action. A UUID is ideal: 1 to 255 printable characters, sent bare or as a quoted string.
- The first request runs, and its answer (status and body) is kept for **24 hours** for that credential.
- A retry with the same key and the same body gets that same answer back, with `Idempotent-Replayed: true`. Nothing happens a second time.
- A retry while the first is still running gets `409 idempotency_in_progress` with `Retry-After`. Retry shortly.
- The same key with a different body or path is `422 idempotency_key_reused`. A malformed key is `400 bad_idempotency_key`.
- Errors that are worth retrying (`5xx`, `429`, `408` and `409`) aren't kept, so a retry after one of those runs again.

## Shorter windows

`Idempotency-Window: <seconds>` (60 to 86400) keeps the key for less than a day, counted from the first request. Use it when identical requests can be real repeats later on. Our own MCP server uses 600 seconds.

## What's safe without a key

These already refuse to do the same work twice:

- `POST /contacts` and `POST /events` attach to an existing contact when the email or phone matches, even when two copies arrive at once. On `/events`, the same inquiry within 10 minutes adds no second note and sends no second alert.
- `POST /site-leads` is deduplicated by its own `submissionId`.
- `POST /flows/{id}/enroll` enrolls a contact once.

Everything else (tasks, appointments, calendar bookings, notes, deals, tours and their stops, and webhooks) is created again on a retry without a key.

## Related

- [Requests, errors and limits](https://brokerandagent.com/developers/api/requests)
- [Send leads](https://brokerandagent.com/developers/api/leads)

---

Source: https://brokerandagent.com/developers/api/idempotency
