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.

Updated Nov 11, 2026

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.

Shell
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.

Something missing or wrong? Email support@brokerandagent.com and we’ll fix it.