The Maple API supports idempotency for safe retries of the same requests without causing unintended consequences. This feature is particularly useful in cases where network issues or system failures can cause duplicate API requests to be sent to the server. This helps provide improved reliability, better user experiences and simplified error handling in your application.

​
Requests

To use the API idempotency feature, you must first generate a unique identifier to be used as the idempotency key. The keys themselves can be arbitrary strings with a max length of 64 characters. We recommend the use of UUIDs In order to generate a fully unique keys.

This identifier must be included in your request as the Idempotency-Key header. Although the idempotency key is not required, it is strongly recommended for all POST or PATCH requests. Sending idempotency keys in GET or DELETE requests has no effect as these requests are idempotent by definition. The server will then use this identifier to ensure that the same request is not executed multiple times.

Maple’s idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeedes or fails. Subsequent requests with the same key return the same result, including 400 and 500 errors.

Once the API request is received by the server, the server will check if the identifier is valid and has not been used before. If the identifier is valid and has not been used before, the server will process the request and mark the identifier as used. If the identifier is not valid or has been used before, the server will ignore the request and return the response from the previous request.

You can safely retry requests that include an idempotency key within 24 hours. Once the key expires, Maple will execute those requests again.

For example, you can use an idempotency header to prevent duplication while creating customers in Maple.

curl --request POST \
     --url https://api.maplebilling.com/api/v1/companies/company_id/customers \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
		 --header 'Idempotency-Key: a5a9d072-16a2-4204-a14b-aa2fda1928bd' \

​
Responses

Any request that is performed with an idempotency key will include an Idempotency-Key header in the response to ensure that there is clarity on the key being used.

Maple will also include Idempotency-Used: true in the response to show that a previous response is being replayed.