Idempotency-Key is now wired across side-effect API calls

Speechify now supports Idempotency-Key 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.

This is one of those changes you only notice when it is missing. The happy path looks identical. The bad path stops being expensive.

When should I send an idempotency key?

Send one when your client might retry a request after the first attempt may 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 for each logical operation. A UUID is fine.

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

Do not reuse it for a different body. If you do, Speechify returns 409 idempotency_conflict instead of guessing which request you meant.

How retries behave

For 24 hours, the same key and same body get the first response back. 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 it committed the operation, the claim is released so you can try again.

Replayed responses include:

Idempotent-Replayed: true

Log both Idempotency-Key and X-Request-ID. One identifies the operation you retried, the other identifies the individual HTTP request.

The full behavior is in the idempotency guide.