Idempotent requests

The API supports idempotency so you can safely retry a write without performing the same operation twice. An idempotency key identifies repeated attempts of the same operation.

To make an idempotent request, generate an Idempotency-Key and include it in the request header. You can create keys however you prefer, but we recommend using UUIDv4 or another high-entropy random string to avoid collisions.

When an idempotency key is required

All authenticated POST requests require an Idempotency-Key except the external-account verification endpoint and routes under /v1/webhooks/*. GET, PUT, PATCH, and DELETE requests do not currently require it.

Use a different key for each operation. Reuse a key only when retrying the same method, path, and payload:

curl --request POST \
     --url https://api.gravv.xyz/v1/customers \
     --header 'Api-Key: <API_KEY>' \
     --header 'Idempotency-Key: 979879887678789_attempt_1' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "first_name": "john",
  "middle_name": "sample",
  "last_name": "doe",
  "email": "john.doe@example.com",
  "phone": "+15555550101",
  "type": "individual",
  "gender": "male",
  "date_of_birth": "2024-04-16",
  "external_id": "individual_12345",
  "address": {
    "address_line1": "1800 N Pole St",
    "address_line2": "Suite 202",
    "city": "Orlando",
    "postal_code": "32801",
    "state": "US-FL",
    "country": "US"
  }
}
'

Retry behavior

Gravv stores the first non-server-error response for 24 hours:

When you receive 409, wait for the number of seconds in Retry-After and retry with the same key and payload. Generate a new key when the operation or payload changes.