Skip to main content
A request can succeed even when your server times out before receiving the response. If you retry with a new idempotency key, Brightalk could create the same call, batch, or Automation run twice. Reuse the same Idempotency-Key and Brightalk can return the original result instead.

​
Three rules

  1. One logical action, one key. Generate a unique, nonsecret value before the first request.
  2. Same action, same key. Within 24 hours, if the request times out, the connection fails, or a response explicitly tells you to retry (for example, with Retry-After), resend the same method, path, API version, semantically identical body, and key.
  3. Changed action, new key. Use a new key when the API version or body changes, or when you intentionally want another call, batch, or Automation run.
The following header-only excerpt intentionally omits the required JSON body and Content-Type header.
Keep order-8f4c2-call-1 with the business action. It is not an authentication secret, but it must not contain a phone number, contact data, or another secret. After 24 hours, do not assume the old idempotency claim prevents duplication. Confirm whether the original action occurred before submitting it again.

​
Where the header is required

The header is required on exactly these four operations: Omitting it returns 400 idempotency_key_required.

​
Where the header is optional

The header is optional on state-machine controls. Adding it makes a completed result replayable:

​
What Brightalk returns

Wait for the Retry-After interval before retrying an in-progress request. Validation failures are not stored as completed idempotent results.

​
Advanced details

Claims are retained for 24 hours and scoped by organization, API key class, API version, HTTP method, and normalized path. Rotating one bt_live_ key to another does not reset a claim for the same key class; reuse the original idempotency key when retrying the same logical request after rotation.