Idempotency in Codat's API calls

Understand how to make idempotent requests to Codat's POST and PATCH endpoints

What is idempotency?

In the context of APIAPI A set of rules and protocols that allows different software applications to communicate with each other. Codat provides APIs for accessing financial data from accounting, banking, and commerce platforms. requests, idempotency ensures that the outcome of executing multiple identical requests has the same outcome as executing the request once. It prevents the creation of duplicate records if an APIAPI A set of rules and protocols that allows different software applications to communicate with each other. Codat provides APIs for accessing financial data from accounting, banking, and commerce platforms. request needs to be retried due to network issues or timeouts.

For example, if you submit the same POST request to create an invoice multiple times, including an idempotency key in the request ensures only one invoice is created.

Idempotency in Codat requests

You can include an Idempotency-Key header with a unique GUID value when making POST or PATCH requests to all of Codat's endpoints that support these methods. Codat will cache the initial response and will use it on all following requests with the same Idempotency-Key header. This cache lasts 90 minutes.

💡 Tips and traps

• The Idempotency-Key header must be a unique GUID.
• You can only include a single Idempotency-Key header into your request.
• You can only include the Idempotency-Key header in POST or PATCH requests.
• It's not possible to reuse the same Idempotency-Key header across different requests.

Possible error codes

• A request that reuses the same Idempotency-Key header with a different body will result in a 422 Unprocessable Content status code.
• A request that uses an Idempotency-Key matching an existing in-progress request will result in a 409 Conflict status code.

Rate-limited requests and idempotency

A rate limit can come from Codat or from the underlying financial platform. In either case, Codat doesn't cache the resulting 429 Too Many Requests response against your Idempotency-Key. Instead, it discards the response and releases the key.

This means you can retry the request with the same Idempotency-Key once the limit clears. Codat treats the retry as a fresh attempt rather than replaying the earlier 429 from its cache.

Retrying after a 429

Use the Retry-After header to decide when to retry, and keep your original Idempotency-Key so that Codat still protects the eventual successful write against duplication. For more detail, see Rate limits.

This applies only to 429 responses. Codat caches every other response as usual and replays it for matching Idempotency-Key requests, including deterministic 4xx errors such as 400, 409, and 422, and 5xx server errors.