You are viewing the documentation for the older version of our API (V1). Click here for information on upgrading to the latest version (V2).
You are viewing the documentation for the older version of our API (V1). Click here for information on upgrading to the latest version (V2).

Idempotent requests

Idempotency is critical in building a fault-tolerant HTTP API that enables safe and reliable retrying of requests, without accidentally duplicating or repeating the same operation twice. To perform an idempotent request, a unique idempotency key must be provided to the server along with the request options. The server uses this key to recognize and distinguish subsequent retries of the same request. GET requests are inherently idempotent, and they return the same response for every duplicate request. Adding an idempotency key along with the GET request is redundant. On the other hand, POST requests can modify the server state and therefore require an idempotency key to safely retry requests and avoid unintended consequences such as creating duplicate records.

To make an idempotent request in Chargebee, provide the chargebee-idempotency-key header with a unique value for each request. When you send a POST request with the idempotency key, Chargebee checks for an existing record for that key. If there is a record, Chargebee returns the response for that record with a response header chargebee-idempotency-replayed set to true, implying Idempotency being replayed, instead of processing the request again. If there is no existing record for the idempotency key, Chargebee creates a new record for the request. This helps the server make sure that it doesn't process the same request twice. We recommend using the "UUID" [RFC4122] or a similar random identifier as an idempotency key.

Note: Idempotency keys can be upto 100 characters in length. Estimate APIs do not support Idempotency.

As the idempotency functionality requires some bookkeeping, you might notice a slight increase in the response time for the idempotent requests.

Chargebee has an idempotency window of 30 minutes, during which time any requests with the same idempotency key and parameters will be considered as a replay of the original request.

Note: Replace the << UUID >> in the sample with a unique string.

Here is an example of how an Idempotent request can be made in a /customer request. The idempotency key can be set in the chargebee-idempotency-key header. Users can identify a replay request by accessing the chargebee-idempotency-replayed header, which will be set to true during a replay.

# Replace  <<UUID>> with a unique string
curl  https://{site} \
    -H "chargebee-idempotency-key : <<UUID>>" \
    -u {api-key}: \
    -d customer[email]=""

Error Handling

When an error occurs, it is important to handle it appropriately to ensure that the system is informed of the issue and provided with clear guidance on how to proceed. This may involve returning an error message, retrying the request after a certain amount of time, or taking other actions to resolve the underlying issue.

    Error Code     Description    Meaning
 400  Bad Request

This error can happen due to the following reasons:

  • chargebee-idempotency-key header value is empty.

  • chargebee-idempotency-key header exceeds 100 characters.  

 409  Conflict  This indicates that the requested operation cannot be completed at this time due to a conflict with another request that is currently being processed. Additionally, a retry-after header will be included in the response, specifying the recommended number of seconds to wait before retrying.
 422 Unprocessable Entity   This error occurs when retrying a request with different parameters than the original request. Furthermore, this error can also occur because request contains invalid data or is missing required parameters.
To ensure that requests are not unintentionally misused, we verify the incoming retry request signature by comparing the URI path, request body and headers with the original request. In the event that they do not match, this error will be thrown. It is important to ensure that these components match to replay the original response.
5xx  Server Errors  This indicates that an error has occurred on the server side and the requested operation cannot be completed at this time.
These errors are cached, which means that if the request is retried within the Idempotency window, the same response will be returned to the user. 
However, if the user still wants to process the request inspite of getting a 5xx error, they can do so by sending the same request using a new chargebee-idempotency-key.