4.3 KiB

Raw Permalink Blame History

MSC3848: Introduce errcodes for specific event sending failures.

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.

Proposal

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:

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:

Potential issues

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.

Alternatives

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.

Security considerations

None.

Unstable prefix

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..

Dependencies