API documentation

Idempotency and retries

Retry any POST safely without sending or charging twice.

Every POST accepts an Idempotency-Key header: 1 to 255 printable ASCII characters, no spaces. Use one unique value per operation, such as your own order id.

curl -X POST https://watsy.me/v1/verify \
  -H "Authorization: Bearer $WATSY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: signup-8841" \
  -d '{
    "phone": "07701234567"
  }'

Rules

Situation	Result
Same key and same request within 24 hours	The stored response is replayed with `Idempotent-Replayed: true`. Nothing is sent or charged again
Same key with another path or body	`409 idempotency_conflict`
Same key while the first request is still running	`409 idempotency_conflict`. Retry in a moment
The first request failed (any error)	Not stored. You may retry with the same key

The fingerprint covers the method, the path and the raw body bytes. Resend exactly the same bytes.
Keys are scoped per project and expire after 24 hours.
An in-flight request that never finished is treated as abandoned after one minute, and the key can be used again.

Important for checks

A code is consumed once. If the response of POST /v1/verify/{id}/check was lost, repeat it with the same Idempotency-Key to get the original valid: true. Without the key, a second check returns valid: false.