Idempotency

Idempotency is when a partner makes the same API call with the same input parameters multiple times and the same response is returned each time. Basically, an identical request should return an identical 20 result when done twice, two thousand, or two million times.

With the BaaS API, idempotency is implemented using the requestId. For example, a successful POST /enrollments API call with the same requestId will always produce and return the same results.

If the requestId is the same, the payload must also be the same. If the payload changes, then that is a different request. If an operation was incomplete when an idempotent call was made, assuming no additional failures or errors occur, the operation will be completed as originally intended

A common scenario for an idempotent call is when an initial API call either fails or times out. The client may not know if it succeeded, failed, or partially completed. A successful idempotent call will complete the operation and return a result as if it was fully completed in the first call.

BaaS APIs Idempotency

In the BaaS APIs, true idempotency has been implemented with the POST /enrollments endpoint.

Example:

In response to a HTTP Status 503, the caller should retry their call, up to 3 times with exponential backoff, by sending in the exact same request. The exact same request is needed to allow for idempotency logic implementations and for request resumption/completion in the event of a transient error.

Retry 1

Call should retry after a randomized wait time of 1 - 1000 milliseconds

Retry 2

Call should retry after a randomized wait time of 1000 - 5000 milliseconds

Retry 3

Call should retry after a randomized wait time of 5000 - 30000 milliseconds

If all three retries are done and the error is still received, the call should be considered failed. The call should not be made again automatically. New requests should be generated and submitted for further attempts.

🚧

A retry should not be attempted on a HTTP Status 400 or 500.

API Locking

The following endpoints support API locking by preventing overlapping API calls. If multiple calls are made to the endpoint, the API will be locked based on the value noted in the tab.

Response Codes