Overview

Moody's RMS Platform APIs support idempotency, which allows you to safely retry service requests that might have failed due to connection issues, without accidentally performing the same operation twice. This behavior is useful when duplicate requests are sent either unintentionally or due to a timeout from network error, but no response is received.

Idempotency provides a way to reconcile failed requests with a server by allowing users to retry API requests safely. A method is idempotent if it guarantees similar results when you send an identical request multiple times. You can retry them several times without changing the result.

• Platform API resources using the GET, PUT, and DELETE methods are idempotent by default.
• Platform API resources using the POST method are not idempotent.

Sending idempotency keys in GET, PUT, and DELETE requests have no effect.

Sending idempotency keys

The Platform API guarantees idempotency for safely retrying POST requests without accidentally performing the same operation twice. Consequently, POST requests accept idempotency keys.

To perform an idempotent request, you must provide an additional X-RMS-RequestId in the request header. Including this unique key in the header makes the POST request idempotent by prompting the API to keep records to prevent duplicate operations.

When you include the key in your request, make it is sufficiently unique. To avoid any duplication, use Universally Unique Identifier (UUID) for the X-RMS-RequestId parameter.

The X-RMS-RequestId key expires after 24 hours. By using the idempotency key, you can safely retry requests if the second request occurs within 24 hours from when the server first receives the key.

In case of a bad request (error code 400), fix the inputs in the request and add a new idempotent key for the new request. If you get a 409 error, it means that the request processing is not finished yet. In this case, wait for some time and retry.