Idempotency - Dialbird API

Write endpoints (POST /contacts, POST /messages) accept an optional Idempotency-Key header so you can safely retry a request after a network error without performing the operation twice.

Using a key

Generate a unique key per logical operation (a UUID works well) and send it on the request. Keys can be up to 255 characters.

curl -X POST https://app-staging.dialbird.io/api/v1/messages \
  -H "Authorization: Bearer $DIALBIRD_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f3c1d9a-1b2c-4d5e-9f01-abcdef123456" \
  -d '{ "to": "+15551234567", "body": "Hello!" }'

Behavior

Scenario	Result
Retry with the same key and identical body	The original response is replayed; the operation does not run again.
Reuse the key with a different body	`409 idempotency_key_reused`.
Retry while the first request is still in flight	`409 idempotency_in_progress`.

Keys are retained for 24 hours. After that, the same key is treated as new.

Derive the key from a stable identifier in your own system (for example, an order id or message draft id) so retries from any part of your code reuse the same key.

Handling conflicts

A 409 response uses the standard error envelope. On idempotency_in_progress, wait briefly and retry the same request — the original will have completed and its response will be replayed.