Retrying safely with idempotency keys
Send an Idempotency-Key with a POST so a retry after a timeout never creates the same task, appointment
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
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 happensa second time. - A retry while the first is still running gets
409 idempotency_in_progresswithRetry-After. Retry shortly. - The same key with a different body or path is
422 idempotency_key_reused. A malformed key is400 bad_idempotency_key. - Errors that are worth retrying (
5xx,429,408and409) aren’t kept, so a retry after one ofthose 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
What’s safe without a key#
These already refuse to do the
POST /contactsandPOST /eventsattach 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 sendsno second alert. POST /site-leadsis deduplicated by its ownsubmissionId.POST /flows/{id}/enrollenrollsa contact once.
Everything else (tasks, appointments, calendar bookings, notes, deals, tours and their stops, and webhooks) is created again on a retry
Related#
Something missing or wrong? Email support@brokerandagent.com and