Core concepts

Idempotency

Safe to retry: if your network drops or you get a 5xx, just retry the same request with the same idempotencyKey. We'll return the original response, never double-send.

How to use it

Pass a unique key per logical request as idempotencyKey. UUIDv4 works well; even your own primary key works if it's stable.

curl -X POST 'https://api.bluereplies.com/v1/messages' \
  -H "x-api-key: $BLUEREPLIES_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "to": "+15551234567",
    "body": "Welcome!",
    "idempotencyKey": "welcome-msg-customer-7421"
  }'

Window is 24 hours. After that, the same key can be reused. Keys are scoped to your customer + endpoint, so the same key on a different endpoint is treated as a different request.

Behavior

First request — processes normally, response cached for 24h.
Retry with same key + same body — returns the cached response, no side effects.
Retry with same key + DIFFERENT body — returns 409 CONFLICT with the original body in error.details.
Same key after 24h — treated as a fresh request.

When to use it

Sending OTP codes — never want to send twice if the user retries
Order confirmations — exactly-once is critical
Any retry loop in your client (auto-retry on network error)
Cron jobs that fire every N seconds with eventual consistency requirements

For more best practices, see Stripe's classic "Designing robust and predictable APIs with idempotency" — same principles apply here.