API reference

Idempotency

A timeout does not tell you whether your message was queued. An idempotency key lets you retry without the customer getting it twice.

How to use it

Add an Idempotency-Key header to POST /v1/messages and POST /v1/otp/send. Choose a value that names the thing you are doing, not the attempt: order-4821-confirmation rather than a random value generated on each try.

curl

curl https://api.getoxtro.com/v1/messages \
  -H "Authorization: Bearer $OXTRO_API_KEY" \
  -H "Idempotency-Key: order-4821-confirmation" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "conn_123",
    "to": "+213555123456",
    "text": "Your order ORD-4821 has been confirmed."
  }'

What happens on a repeat

Situation	Result
Same key, same body, first request finished	The first response is returned again, with the header `Idempotent-Replayed: true`. Nothing new is sent.
Same key, same body, first request still running	`409 CONFLICT`. Retry shortly.
Same key, different body	`409 IDEMPOTENCY_CONFLICT`. Use a new key for a new message.
First request ended in a `5xx`	The key is released, so the retry runs normally.

Rules

Keys are remembered for 24 hours and are scoped to your workspace.
The body is compared byte for byte. Resend exactly the same JSON, not an equivalent object serialised again in a different key order.
4xx responses are remembered too. If a send failed with CONNECTION_OFFLINE, the same key keeps returning that error for 24 hours, so use a new key once the number is linked again.
Requests without the header are never deduplicated.