The API supports idempotent requests allowing the safe retrying of
requests without accidentally performing the same operation again. When making an
idempotent request, if an error occurs in the request to the API (such as
a timeout or loss of connection), you can safely retry the request without the
risk of creating a second resource or performing the update twice.
Idempotency works by storing the status code and body of the first
response for a given idempotency key, regardless of whether the request
succeeded or failed. Subsequent requests with the same idempotency key will
return the same response.
An idempotency key is a unique key generated by you that the API uses to
identify subsequent retries of the same request. We recommend using V4 UUIDs,
or another random string with enough entropy to avoid collisions. Idempotency
keys can be up to 255 characters long, and remain valid for 24 hours, after
which the idempotency key may be reused for another request.
The response of an idempotent request is only saved if the API started
executing. If your request fails validation or the request conflicts with
another that was performed concurrently, no response is saved. It is safe to
retry these requests.
Currently, only the POST /transactions
endpoint supports idempotent requests.
Making an idempotent request
To make an idempotent request, specify the Idempotency-Key
header in the
request.
curl -i -X POST "https://api.example.gr4vy.app/transactions" \
-H "Authorization: Bearer [JWT]" \
-H "Idempotency-Key: bffa9ce6-7a8a-449c-889a-65bd2ee86903" \
-d "{...}"
Most of
our SDKs support passing through this header on the
POST transactions
call.
Concurrent requests
When making an idempotent request using the same Idemoptency-Key
as a previous
request, and the original request is still being processed, you will receive an
error. You can safely retry this request. We recommend applying an exponential
back-off when retrying transactions.
{
"type": "error",
"code": "concurrent_request",
"status": 409,
"message": "A request with this idempotency key is still being processed. Retry later.",
"details": []
}
Conflicting requests
When making an idempotent request using the same Idempotency-Key
as a previous
request, and the request is not the same (for example, the request body is
different), you will receive an error. Retrying this request will not change the
error response. You should check your request.
{
"type": "error",
"code": "bad_request",
"status": 400,
"message": "Idempotency key already in use.",
"details": []
}