When performing an action on the C-S API, sometimes requests will fail with
a generic M_FORBIDDEN error with implementations providing a more meaningful
context in the error field. While some client implementations have taken it
upon themselves to scan these error fields for probable causes, this isn't a
particularly safe or spec-complaint way to react to errors.
Some examples of failures which require more standardized error information include already-joined errors when a user tries to invite another user to a room, or being unable to send an event into a room due to lacking the required power level.
For this reason, this proposal suggests including new errcode definitions
which provide more specific information about the failure.
New errcode would be introduced into the error body of a response
(https://spec.matrix.org/v1.3/client-server-api/#standard-error-response).
M_ALREADY_JOINED would be fired when a membership action fails when the authenticated user
is already joined to the room.
This would cover endpoints:
- POST /_matrix/client/v3/rooms/{roomId}/invite
- POST /_matrix/client/v3/rooms/knock/{roomIdOrAlias}
- PUT /_matrix/client/v3/rooms/{roomId}/state/{eventType}/{stateKey}
Note that it would not cover endpoints where trying to join a room when the
user is already joined would no-op, like POST /_matrix/client/v3/join/{roomIdOrAlias}.
M_INSUFFICIENT_POWER would be when the authenticated user does not have the required power level to
perform an action in the room.
M_NOT_JOINED would be when the authenticated user is not joined to a room, but attempts to perform
an action in it.
Both errcodes would cover endpoints:
- POST /_matrix/client/v3/rooms/{roomId}/invite
- POST /_matrix/client/v3/rooms/knock/{roomIdOrAlias}
- POST /_matrix/client/v3/rooms/{roomId}/unban
- POST /_matrix/client/v3/rooms/{roomId}/ban
- POST /_matrix/client/v3/rooms/{roomId}/kick
- PUT /_matrix/client/v3/rooms/{roomId}/state/{eventType}/{stateKey}
- PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}
Changing long-established error codes in Matrix will be fraught with risk, as many clients will need updating to support the new error types. Failure to do so might lead to unexpected behaviours or confusing error messages. For this reason, the unstable implementation will continue to provide the old errcode in the body of the error while providing the new proposed errcode under its own field. This gives clients a chance to adapt to the new errcode / ensure their behaviours with unexpected errcodes are acceptable.
We could introduce a second field to the error body for more specific errors, but this would likely make error handling in clients much more complicated. There is precedence already in the spec for specific error codes for specific failures, so there is little need to subclass.
None.
While this MSC is not considered stable for implementation, implementations should use org.matrix.msc3848.unstable.errcode
as a prefix to the fields on the error body. M_FORBIDDEN will still be emitted as a errcode while the
MSC is unstable, and will be replaced when the spec stabilizes.
The errcodes will be have the prefix M_ replaced with ORG.MATRIX.MSC3848..
None.