Skip to main content
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), the request can be safely retried 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 return the same response. An idempotency key is a unique key generated that the API uses to identify subsequent retries of the same request. It is recommended to use 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 the 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 the 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, an error is received. This request can be safely retried. It is recommended to apply 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), an error is received. Retrying this request will not change the error response. The request should be checked. 
{
  "type": "error",
  "code": "bad_request",
  "status": 400,
  "message": "Idempotency key already in use.",
  "details": []
}