Platform
Idempotency
Every write accepts an Idempotency-Key, so a retried request runs at most once and answers with the first outcome.
Every POST, PUT, PATCH and DELETE accepts an optional Idempotency-Key header: 1–255 visible ASCII characters — a UUID, or an id from your own system such as order-1042-confirmation. With it, the request runs at most once for that key, and what happened is stored for 24 hours.
curl -X POST 'https://api.trovacast.com/v1/messages' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: order-1042-confirmation' \
-H 'Content-Type: application/json' \
-d '{
"type": "template",
"contactId": "CONTACT_ID",
"template": {
"name": "order_confirmation",
"language": "en"
},
"variables": {
"var1": "Aarav",
"var2": "#1042"
}
}'Without the header a write is not deduplicated: send one on every write you might retry. The Node.js, Python and Go SDKs send one on every write and reuse it across their own retries.
What a retry with the same key gets
| The first request with the key… | A retry with the same key and the same request… |
|---|---|
| succeeded (2xx) | gets the stored response, with Idempotent-Replayed: true, without running again. |
| was refused (any 4xx) | runs again. Fix the cause first (top up, correct the body): a refusal happens before anything changes. |
| failed with a 5xx on a re-runnable endpoint | runs again, and converges on one outcome. |
| failed with a 5xx that changed nothing | runs again. |
| failed with any other 5xx | gets the same error again, with Idempotent-Replayed: true. |
| is still running | 409 IDEMPOTENCY_KEY_IN_FLIGHT with Retry-After. |
A key reused for a different request (another body or path) is 422 IDEMPOTENCY_KEY_REUSED, whatever state the first request is in. Keys are per API key and per endpoint: two of your keys, or two endpoints, never share one.
Why a 5xx can be replayed
A 5xx can come after the endpoint already acted — a call placed, an endpoint created, a provider that timed out after accepting — so running the request again could do it twice. An error answered with Idempotent-Replayed: true is therefore final for that key: read the resource to find out whether the first attempt took effect, and only if it did not, send the request again with a new key.
Re-runnable endpoints
These endpoints' writes converge when run again, so a 5xx stores nothing and a retry with the same key simply runs again. The contract marks them x-idempotent-rerun: true.
| Endpoint | Why it converges |
|---|---|
POST /v1/messages | The message is keyed on the Idempotency-Key and the request: a retry finds the message the first attempt queued. |
POST /v1/calls | The call is keyed the same way: a retry answers the call the first attempt placed; one after a dial the carrier refused dials afresh. |
POST /v1/calls/{callId}/hangup | Ending a call is idempotent: a call already ending is asked again, one already over is answered as it stands. |
DELETE /v1/calls/{callId}/recording | Erasure is idempotent (a repeat answers 204). |
POST /v1/messages/{messageId}/read | A read receipt creates nothing; sending it twice is the same as once. |
DELETE /v1/contacts/{contactId} | Erasure is idempotent (a repeat answers 204). |
DELETE /v1/organizations/{organizationId} | A repeat while it runs changes nothing; after a failed run it starts again. |
Errors that changed nothing
Two failures are raised only where the platform knows the request did nothing, so the key is released on every endpoint and a retry with it runs again:
503MESSAGING_TRANSPORT— Meta, Amazon SES or SNS was never reached. (A provider that timed out *after* the request left is504MESSAGING_PROVIDER_UNCONFIRMED, which is not one of these.)503WHATSAPP_CONNECT_UNAVAILABLEonPOST /v1/whatsapp/connect-sessions— no link was issued.
A safe retry loop
- Mint one key per logical operation (or derive it from your own id) and keep it for every attempt of that operation.
- On a timeout, a network error,
429,500,502,503,504or409 IDEMPOTENCY_KEY_IN_FLIGHT, wait — exponentially, with jitter, never less thanRetry-After— and send the same request with the same key. - Stop at any 4xx, and at any error carrying
Idempotent-Replayed: true. - For a new operation, use a new key — an identical request under a reused key still answers the original.