Idempotency

GrailPay's APIs support idempotency, enabling you to safely retry requests without accidentally duplicating operations.

To make an idempotent request, include an additional Idempotency-Key header. This key prevents the creation of duplicate objects or repeated updates if a connection error occurs, allowing you to safely retry the request.

An idempotency key is a unique value generated by the client and recognized by the server to identify retries of the same request. We recommend using V4 UUIDs or similar random strings to minimize the risk of collisions. The maximum length for an idempotency key is 255 characters.

The idempotency mechanism saves the response status code and body of the initial request associated with a specific idempotency key. Any subsequent requests to the same endpoint with the same idempotency key will yield the identical response for at least 24 hours. After this period, the key is purged from the system, and using the same key will result in a new request.

Only POST and PUT request endpoints support idempotency keys. Using these keys with other types of requests is ineffective and should be avoided.

For more information, please see the example below, which illustrates how to submit the Idempotency-Key header in a GrailPay request:

curl --location 'https://api-sandbox.grailpay.com/3p/api/v1/register/person' \
--header 'Accept: application/json' \
--header 'Idempotency-Key: afc24e55-8321-4172-8903-67e7ed80f07b' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "first_name": "Will",
    "last_name": "Clance",
    "address": {
        "line_1": "681 Avenue C",
        "city": "Bayonne",
        "state": "NJ",
        "zip": "07002"
    }
}'