Idempotency

All of our API endpoints support idempotency, in which a request defines a state, not an action. If you repeat an idempotent request through accident or because you’re unsure if an earlier request made it through, the repeated requests won’t accumulate with unintended results. If you repeat an idempotent request three times to credit an account with $30, for example, you won't accidentally credit$90, you will credit the intended $30.

The response for any request made with an idempotency header is cached, and a subsequent request with the same idempotency key will return the cached response, including the initial response status code. The exceptions are requests that returns a 500-series status code (since they may not have been fully executed) and requests that are rate-limited and return a 429 status code. In these two cases, a repeat of the request with the same idempotency key will re-execute the request and not return a cached response.

Our endpoints support idempotency as defined in the IETF draft specification. To send an idempotent request, add the header Idempotency-Key: {KEY} to your request, where {KEY} is an arbitrary unique value that you define. Add the same header and key value to each repeated idempotent request.

Each idempotency key and any resulting cached responses persist for 7 days and then disappear.

An example of a cURL request using an idempotent request header with an example key value of 259:

Shell

curl -X POST https://api-sandbox.synctera.com/v0/customers \
  -H 'Idempotency-Key: 259'