Add info_link field

proposals/4335-user-limit-exceeded.md

@@ -18,9 +18,9 @@ specific error messages and handle user-specific limitations appropriately.
 
 ## Proposal
 
-This proposal adds a new error code `M_USER_LIMIT_EXCEEDED` to the Matrix specification. This error
+This proposal adds a new [common error code](https://spec.matrix.org/v1.15/client-server-api/#common-error-codes)
-code should be returned when a user has exceeded limits that are specifically associated with their
+`M_USER_LIMIT_EXCEEDED` to the Matrix specification. This error code should be returned when a user has exceeded
-account, such as:
+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.
@@ -31,35 +31,30 @@ account, such as:
 * **Account tier restrictions**: When a user's account type (free, premium, etc.) prevents them
   from performing certain operations.
 
-The error should be returned with HTTP status code **403 Forbidden** to indicate that the operation
+The error response would also contain an `info_url` value which provides a URI that the client can link
-is not permitted due to the user's current limits.
+the user to in order to get more context on the error.
 
-### Error Response Format
+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`.
 
-When returning this error, servers should use the standard Matrix error response format:
+An example response body for the error might look as follows:
 
 ```json
 {
   "errcode": "M_USER_LIMIT_EXCEEDED",
+  "info_url": "https://example.com/homeserver/?limit_type=quota",
   "error": "User has exceeded their storage quota of 10GB"
 }
 ```
 
-The human-readable `error` field should provide specific information about what limit was exceeded
-and, where possible, include details about the current usage and limit values to help users
-understand their situation.
-
 ### Applicable Endpoints
 
 This error code can be returned by any Matrix Client-Server API endpoint where user-specific limits
-might be enforced. Examples might include:
+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
 
-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`.
-
 ### Distinction from Other Error Codes
 
 This error code is distinct from:
@@ -73,8 +68,12 @@ This error code is distinct from:
 
 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. Implementers should ensure
+rely on the human-readable `error` field to provide specific details. Instead the `info_url`
-they provide clear, actionable error messages.
+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
@@ -106,21 +105,21 @@ None as only adding a new error code.
 
 ## Unstable prefix
 
-While this proposal is being developed and refined, implementations should use the unstable prefix
+While this proposal is being developed and refined, implementations should use the prefix the
-`ORG.MATRIX.MSC4335.M_USER_LIMIT_EXCEEDED` instead of `M_USER_LIMIT_EXCEEDED`.
+`errcode` and `info_url` fields with `org.matrix.msc4335.` and use a value of `M_UNKNOWN` for
+`errcode`.
 
 For example:
 
 ```json
 {
-  "errcode": "ORG.MATRIX.MSC4335.M_USER_LIMIT_EXCEEDED",
+  "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"
 }
 ```
 
-Once the MSC is accepted and the error code is included in the Matrix specification, implementations
-should transition to using the stable `M_USER_LIMIT_EXCEEDED` error code.
-
 ## Dependencies
 
 None.