Idempotency | Speechify API

Use Idempotency-Key on side-effect POST requests that might be retried by your client, network, job runner, or webhook handler. If the first attempt reaches Speechify but the response is lost, retry with the same key and body. The API returns the first result instead of running the operation again.

The endpoint reference lists Idempotency-Key on every operation that supports it.

When to send a key

Send a key for requests that create something outside the request itself:

Use case	Example
Start a call	`POST /v1/agents/outbound-calls`
Start a batch	`POST /v1/agents/batch-calls`
Purchase a phone number	`POST /v1/agents/phone-numbers/purchase`
Create a workspace	`POST /v1/workspaces`

Do not send it on GET, PATCH, PUT, or DELETE. Those methods are read-only or already idempotent by HTTP semantics.

Choose the key

Generate a fresh, opaque key for each logical operation. A UUID is fine.

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

Keys can be up to 255 characters. Reuse the same key only when retrying the same operation with the same body.

Retry behavior

Request	Result
Same key, same body	The first response is replayed for 24 hours.
Same key, different body	`409 idempotency_conflict`.
Same key while the first request is still running	`409 idempotency_conflict`.
First response was a server error	The claim is released, so you can retry.

A replayed response includes:

1 Idempotent-Replayed: true

Raw HTTP example

$ curl -X POST https://api.speechify.ai/v1/agents/outbound-calls \
>   -H "Authorization: Bearer $SPEECHIFY_API_KEY" \
>   -H "Content-Type: application/json" \
>   -H "Idempotency-Key: 4c7f0a78-0a61-42b4-8b8a-60b307b18f0c" \
>   -d '{
>     "agent_id": "agent_demo0001",
>     "phone_number": "+15555550123"
>   }'

Error shape

If a key is reused incorrectly, the response uses the standard error envelope:

1 {
2   "error": {
3     "code": "idempotency_conflict",
4     "message": "This Idempotency-Key was already used with a different request."
5   },
6   "request_id": "7f3a2c1b4d5e6f7a"
7 }

Log both Idempotency-Key and X-Request-ID in your job runner. The first identifies the operation you retried. The second identifies the specific HTTP request.