Idempotency-Key on side-effect API calls

`Idempotency-Key` on side-effect API calls

Idempotency-Key is now supported on side-effect API calls where a retry could otherwise create something twice. Start a call, start a batch, buy a number, mint a service-account key, or run another money-path POST with the same key and body, and the API replays the first result instead of running the operation again.

When to send a key

Send one when your client might retry a request after the first attempt may already have reached Speechify:

POST /v1/agents/outbound-calls
POST /v1/agents/batch-calls
POST /v1/agents/phone-numbers/purchase
service-account key creation and minting paths
spend and dispatch paths with external effects

Use a fresh opaque value per logical operation — a UUID is fine:

1 Idempotency-Key: 4c7f0a78-0a61-42b4-8b8a-60b307b18f0c

How retries behave

For 24 hours, the same key and body return the first response. A replay includes:

1 Idempotent-Replayed: true

If the first request is still running, or the body differs, the API returns 409 idempotency_conflict. If the first attempt failed with a server error before committing, the claim is released so you can retry.

Log both Idempotency-Key and Speechify-Request-Id: one identifies the operation you retried, the other the individual HTTP request. See the idempotency reference for full behavior.