Eventual consistency

Use this page to understand what eventual consistency means in the MassiveMusic API and how to handle it safely in your integration.

Our API is a globally distributed system, built to tolerate localised failure so the platform as a whole can keep running. Because of this distributed design, the result of a write operation may not be immediately visible to a subsequent read or dependent write.

In practice, this means a resource can be successfully created or updated, but a follow-up request made immediately afterwards may briefly behave as if that change has not happened yet.

What eventual consistency means

Eventual consistency means the platform will converge on the latest state, but not every part of the system will reflect that state at exactly the same moment.

For example, you might create a user successfully and then make a second request that depends on that user. If that second request reaches a part of the system that has not yet observed the new state, the request can fail temporarily even though the original create request succeeded.

Typical propagation window

There is no fixed propagation window you should rely on. Some updates become visible after a single retry, while others may require multiple retries before the latest state is visible everywhere it needs to be.

For this reason, do not assume that a successful write will always be immediately available to the next request. Design dependent calls to tolerate short propagation delays.

Example 1
You create a new user using /user/create and then immediately attempt to create a subscription for that user.

Expected: The subscription is created.
Actual: You receive an error that the user does not exist.

Example 2
You create a valid subscription for a user, and then immediately attempt to play a track via the /stream/subscription endpoint.

Expected: The track's streaming content is delivered.
Actual: An error is returned saying that the user does not have a valid subscription.

Handling guidance

When a request depends on a resource that was only just created or updated, wrap that request in retry logic.

Follow these rules:

• Retry only requests that depend on recently created or updated resources.
• Use exponential backoff so retries are spaced out rather than sent immediately.
• Expect that one retry may be enough in many cases, but allow for multiple retries.
• Treat these failures as temporary propagation delays when they occur immediately after a successful write.
• Make your retry handling idempotent (safe to repeat) so the same operation can be attempted more than once without creating unintended side effects.

In both of these cases, simply retrying the call once may be sufficient to get the expected result. However, you may need to retry the call multiple times. As such, we recommend wrapping calls that make use of a recently created resource (such as a user, or subscription) with a retry mechanism with exponential backoff:

For example:

Suggested libraries to help you with this:

C# - Polly
Node.js - exponential-backoff