Trovacast

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.

A write with an Idempotency-Key
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 endpointruns again, and converges on one outcome.
failed with a 5xx that changed nothingruns again.
failed with any other 5xxgets the same error again, with Idempotent-Replayed: true.
is still running409 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.

EndpointWhy it converges
POST /v1/messagesThe message is keyed on the Idempotency-Key and the request: a retry finds the message the first attempt queued.
POST /v1/callsThe 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}/hangupEnding a call is idempotent: a call already ending is asked again, one already over is answered as it stands.
DELETE /v1/calls/{callId}/recordingErasure is idempotent (a repeat answers 204).
POST /v1/messages/{messageId}/readA 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:

  • 503 MESSAGING_TRANSPORT — Meta, Amazon SES or SNS was never reached. (A provider that timed out *after* the request left is 504 MESSAGING_PROVIDER_UNCONFIRMED, which is not one of these.)
  • 503 WHATSAPP_CONNECT_UNAVAILABLE on POST /v1/whatsapp/connect-sessions — no link was issued.

A safe retry loop

  1. Mint one key per logical operation (or derive it from your own id) and keep it for every attempt of that operation.
  2. On a timeout, a network error, 429, 500, 502, 503, 504 or 409 IDEMPOTENCY_KEY_IN_FLIGHT, wait — exponentially, with jitter, never less than Retry-After — and send the same request with the same key.
  3. Stop at any 4xx, and at any error carrying Idempotent-Replayed: true.
  4. For a new operation, use a new key — an identical request under a reused key still answers the original.