Idempotency

Why it matters

Networks fail mid-request. If you POST /v1/activations and the connection drops before you see the response, you don't know whether the activation was created. Retrying naively could charge you twice.

The Idempotency-Key header solves this: send the same key on the retry, get the same result.

How to use

Generate a UUID per logical operation, send it on every retry of the same operation:

KEY=$(uuidgen)
curl -X POST https://api.eveses.com/v1/activations \
  -H "Authorization: Bearer $EVESES_API_KEY" \
  -H "Idempotency-Key: $KEY" \
  -d '{"country":"ua", "service":"telegram"}'

Re-running the exact same call with the same Idempotency-Key returns the original response — no second activation, no second charge.

TTL

Keys are remembered for 24 hours. After that the slot is freed and the same key can be reused as new.

Where it applies

All POST /v1/* endpoints that create or charge: activations, rentals, deposits, extensions. Read endpoints (GET) are already idempotent and ignore the header.

Mismatches

If you reuse the same key with a different body, the API returns 409 idempotency_conflict. Either keep the body identical on retries, or generate a new key.

SDK behaviour

Official SDKs auto-generate idempotency keys for every create call and reuse them on automatic retries. You can override with an explicit key if needed.