matrix-spec-proposals/proposals/4335-user-limit-exceeded.md

MSC4335: M_USER_LIMIT_EXCEEDED error code

Currently, Matrix homeservers lack a standardized error code to indicate when user-related limits have been exceeded. This creates inconsistent client experiences when homeservers need to reject operations due to per-user quotas, rate limits, or resource constraints.

Different implementations may return generic error codes like M_FORBIDDEN or M_TOO_LARGE, making it difficult for clients to provide appropriate user feedback or implement proper retry logic.

A concrete use case for this is the fair usage limits introduced on the matrix.org homeserver.

This proposal introduces a new error code M_USER_LIMIT_EXCEEDED that homeservers can use to signal when a user has exceeded their allocated limits, distinct from general rate limiting or server-wide constraints. This improves the user experience by allowing clients to provide more specific error messages and handle user-specific limitations appropriately.

Proposal

This proposal adds a new common error code M_USER_LIMIT_EXCEEDED to the Matrix specification. This error code should be returned when a user has exceeded limits that are specifically associated with their account, such as:

• Storage quotas: When a user has exceeded their allocated storage space for media uploads, message history, or other persistent data.
• Resource limits: When a user has reached their maximum number of allowed rooms, devices, or other account-scoped resources.
• Feature limits: When a user has exceeded usage limits for specific features (e.g., number of public rooms they can create, number of invites they can send).
• Account tier restrictions: When a user's account type (free, premium, etc.) prevents them from performing certain operations.

The error response would also contain an info_url value which provides a URI that the client can link the user to in order to get more context on the error.

The HTTP response code should be chosen based on the specification for the individual endpoint. For example, the most appropriate code for POST /_matrix/media/v3/upload would be 403 Forbidden.

An example response body for the error might look as follows:

{
  "errcode": "M_USER_LIMIT_EXCEEDED",
  "info_url": "https://example.com/homeserver/?limit_type=quota",
  "error": "User has exceeded their storage quota of 10GB"
}

Applicable Endpoints

This error code can be returned by any Matrix Client-Server API endpoint where user-specific limits might be enforced. Examples could include:

• POST /_matrix/media/v3/upload - When storage quota is exceeded
• POST /_matrix/client/v3/rooms/{roomId}/invite - When invite limits (like maximum participant count) are exceeded

Distinction from Other Error Codes

This error code is distinct from:

• M_LIMIT_EXCEEDED: Used for general rate limiting that applies to all users or based on IP/client
• M_FORBIDDEN: Used for authorization failures or policy violations not related to usage limits
• M_RESOURCE_LIMIT_EXCEEDED: Used for server-wide resource constraints affecting all users
• M_TOO_LARGE: Used when a request is too large (file size, message length, etc.) regardless of user limits

Potential issues

This error code does not specify the exact nature of the limit that was exceeded, which could potentially lead to ambiguity. However, this is consistent with other Matrix error codes that rely on the human-readable error field to provide specific details. Instead the info_url provides a way for the homeserver to apply arbitrary limits without the client having to understand every type in advance.

The homeserver can choose to provide localised and personalised content on the info_url if it wishes.

The error code does not provide machine-readable information about current usage or limits, which could be useful for clients to display progress bars or usage statistics. However, adding such fields would require a more complex specification change and could be addressed in a future MSC if deemed necessary.

Alternatives

Several alternatives were considered for this proposal:

Use M_RESOURCE_LIMIT_EXCEEDED: The existing M_RESOURCE_LIMIT_EXCEEDED error code could be expanded to cover user-specific limits. However, this code is currently used for server-wide resource constraints, and overloading it could create confusion about whether the limit applies to the user specifically or the server generally.

Add structured error information: Instead of a simple error code, a more complex error format could include machine-readable fields for limit types, current usage, and maximum limits. While this would provide more information, it would require a more significant change to the error response format and could be added in a future MSC if needed.

Multiple specific error codes: Separate error codes could be introduced for different types of limits (e.g., M_STORAGE_LIMIT_EXCEEDED, M_ROOM_LIMIT_EXCEEDED). However, this approach would require many new error codes and doesn't provide significant benefits over a single code with descriptive error messages.

Security considerations

None as only adding a new error code.

Unstable prefix

While this proposal is being developed and refined, implementations should use the prefix the errcode and info_url fields with org.matrix.msc4335. and use a value of M_UNKNOWN for errcode.

For example:

{
  "errcode": "M_UNKNOWN",
  "org.matrix.msc4335.errcode": "M_USER_LIMIT_EXCEEDED",
  "org.matrix.msc4334.info_url": "https://example.com/homeserver/?limit_type=quota",
  "error": "User has exceeded their fair usage limit of 2GB"
}

Dependencies

None.