diff --git a/proposals/3848-errcode-specific-failure.md b/proposals/3848-errcode-specific-failure.md new file mode 100644 index 00000000000..f663ba256a8 --- /dev/null +++ b/proposals/3848-errcode-specific-failure.md @@ -0,0 +1,77 @@ +# 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: + - [POST /_matrix/client/v3/rooms/{roomId}/invite](https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3roomsroomidinvite) + - [POST /_matrix/client/v3/rooms/knock/{roomIdOrAlias}](https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3knockroomidoralias) + - [PUT /_matrix/client/v3/rooms/{roomId}/state/{eventType}/{stateKey}](https://spec.matrix.org/v1.3/client-server-api/#put_matrixclientv3roomsroomidstateeventtypestatekey) + +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](https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3roomsroomidinvite) + - [POST /_matrix/client/v3/rooms/knock/{roomIdOrAlias}](https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3knockroomidoralias) + - [POST /_matrix/client/v3/rooms/{roomId}/unban](https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3roomsroomidban) + - [POST /_matrix/client/v3/rooms/{roomId}/ban](https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3roomsroomidban) + - [POST /_matrix/client/v3/rooms/{roomId}/kick](https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3roomsroomidkick) + - [PUT /_matrix/client/v3/rooms/{roomId}/state/{eventType}/{stateKey}](https://spec.matrix.org/v1.3/client-server-api/#put_matrixclientv3roomsroomidstateeventtypestatekey) + - [PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}](https://spec.matrix.org/v1.3/client-server-api/#put_matrixclientv3roomsroomidsendeventtypetxnid) + + +## 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 + +None.