Idempotency

The Sphere API supports idempotency for safely retrying requests without accidentally performing the same operation twice. We recommend using an idempotency keys when creating or updating resources.

Idempotent Keys

To perform an idempotent request, provide an idempotency key to the request headers.

Sphere's idempotency works by indexing the idempotency key of each request, regardless of response status. Requests made with an already used idempotency key will error before processing.

Idempotency keys are up to 255 characters long. It is recommended that you use a random string with enough entropy to avoid collisions; V4 UUIDs are usually sufficient.

-H Idempotency-Key: f189e4d2-8703-48fb-b13f-7f07aab9375d

Sample Request

The following is an example curl request to create a price with an idempotency key:

curl https://api.spherepay.co/v1/price \
  -H "Authorization: Bearer {token}" \
  -H "Idempotency-Key: f189e4d2-8703-48fb-b13f-7f07aab9375d" \
  -d "{
    \"currency\": \"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v\",
    \"network\": \"sol\",
    \"unitAmountDecimal\": "10",
    \"product\": \"product_a65d51a2f2134bfc96326f40734d486f\"
  }"