From a570f6a514b5998707fc7a8e7578bf5f6f2a120c Mon Sep 17 00:00:00 2001 From: Half-Shot Date: Tue, 19 Jul 2022 17:21:30 +0100 Subject: [PATCH 01/10] Initial draft --- proposals/3848-errcode-specific-failure.md | 53 ++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 proposals/3848-errcode-specific-failure.md diff --git a/proposals/3848-errcode-specific-failure.md b/proposals/3848-errcode-specific-failure.md new file mode 100644 index 000000000..c581f6067 --- /dev/null +++ b/proposals/3848-errcode-specific-failure.md @@ -0,0 +1,53 @@ +# MSC3848: Introduce errcodes for specific membership change failures. + +When performing an action on the C-S API, sometimes it will fail if the user is already joined to the room. In +these cases, homeservers will throw a `M_FORBIDDEN` stating that the action wasn't successful. However, it's difficult +to distinguish this kind of failure from insufficient permission errors (or other kinds of errors). This would be +useful, as the caller can then react to the error e.g. refresh it's membership cache if it tries to invite a user +that is already joined. + +## Proposal + +New `errcode` would be introduced into the error body of a response (https://spec.matrix.org/latest/client-server-api/#standard-error-response). + +`M_ALREADY_JOINED` would be fired when a membership action fails when the user is already joined to the room. +This would cover endpoints: + - [POST /_matrix/client/v3/rooms/{roomId}/invite](https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3roomsroomidinvite) + - [POST /_matrix/client/v3/rooms/knock/{roomIdOrAlias}](https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3knockroomidoralias) + - [PUT /_matrix/client/v3/rooms/{roomId}/state/{eventType}/{stateKey}](https://spec.matrix.org/latest/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_INSUFFICENT_POWER` would be when your user does not have the specific required power level to +perform an action in the room. + - [POST /_matrix/client/v3/rooms/{roomId}/invite](https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3roomsroomidinvite) + - [POST /_matrix/client/v3/rooms/knock/{roomIdOrAlias}](https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3knockroomidoralias) + - [POST /_matrix/client/v3/rooms/{roomId}/unban](https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3roomsroomidban) + - [POST /_matrix/client/v3/rooms/{roomId}/ban](https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3roomsroomidban) + - [POST /_matrix/client/v3/rooms/{roomId}/kick](https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3roomsroomidkick) + - [PUT /_matrix/client/v3/rooms/{roomId}/state/{eventType}/{stateKey}](https://spec.matrix.org/latest/client-server-api/#put_matrixclientv3roomsroomidstateeventtypestatekey) + + +## 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. +However, the alternative is keeping the non-specific error codes and having the + +## 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. + +## Security considerations + +None. + +## Unstable prefix + +While this MSC is not considered stable for implementation, implementations should use `org.matrix.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. + +## Dependencies + +None. \ No newline at end of file From 996e861880b0c048d58cb70bfaa1347af5759e1c Mon Sep 17 00:00:00 2001 From: Half-Shot Date: Tue, 19 Jul 2022 17:24:28 +0100 Subject: [PATCH 02/10] tighten lines --- proposals/3848-errcode-specific-failure.md | 27 +++++++++++++--------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/proposals/3848-errcode-specific-failure.md b/proposals/3848-errcode-specific-failure.md index c581f6067..7bc039154 100644 --- a/proposals/3848-errcode-specific-failure.md +++ b/proposals/3848-errcode-specific-failure.md @@ -1,21 +1,25 @@ # MSC3848: Introduce errcodes for specific membership change failures. -When performing an action on the C-S API, sometimes it will fail if the user is already joined to the room. In -these cases, homeservers will throw a `M_FORBIDDEN` stating that the action wasn't successful. However, it's difficult -to distinguish this kind of failure from insufficient permission errors (or other kinds of errors). This would be -useful, as the caller can then react to the error e.g. refresh it's membership cache if it tries to invite a user -that is already joined. +When performing an action on the C-S API, sometimes it will fail if the user is +already joined to the room. In these cases, homeservers will throw a `M_FORBIDDEN` +stating that the action wasn't successful. However, it's difficult to distinguish this +kind of failure from insufficient permission errors (or other kinds of errors). This would be +useful, as the caller can then react to the error e.g. refresh it's membership cache +if it tries to invite a user that is already joined. ## Proposal -New `errcode` would be introduced into the error body of a response (https://spec.matrix.org/latest/client-server-api/#standard-error-response). +New `errcode` would be introduced into the error body of a response +(https://spec.matrix.org/latest/client-server-api/#standard-error-response). -`M_ALREADY_JOINED` would be fired when a membership action fails when the user is already joined to the room. +`M_ALREADY_JOINED` would be fired when a membership action fails when the user +is already joined to the room. This would cover endpoints: - [POST /_matrix/client/v3/rooms/{roomId}/invite](https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3roomsroomidinvite) - [POST /_matrix/client/v3/rooms/knock/{roomIdOrAlias}](https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3knockroomidoralias) - [PUT /_matrix/client/v3/rooms/{roomId}/state/{eventType}/{stateKey}](https://spec.matrix.org/latest/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}`. +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_INSUFFICENT_POWER` would be when your user does not have the specific required power level to perform an action in the room. @@ -29,9 +33,10 @@ perform an action in the room. ## 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. -However, the alternative is keeping the non-specific error codes and having the +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. However, the alternative is keeping +the non-specific error codes and having the ## Alternatives From 593a5bac81cf3eab185dee01d8d5bb62f50ff466 Mon Sep 17 00:00:00 2001 From: Half-Shot Date: Tue, 19 Jul 2022 17:25:18 +0100 Subject: [PATCH 03/10] spelling --- proposals/3848-errcode-specific-failure.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3848-errcode-specific-failure.md b/proposals/3848-errcode-specific-failure.md index 7bc039154..65e841fd5 100644 --- a/proposals/3848-errcode-specific-failure.md +++ b/proposals/3848-errcode-specific-failure.md @@ -21,7 +21,7 @@ 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_INSUFFICENT_POWER` would be when your user does not have the specific required power level to +`M_INSUFFICIENT_POWER` would be when your user does not have the specific required power level to perform an action in the room. - [POST /_matrix/client/v3/rooms/{roomId}/invite](https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3roomsroomidinvite) - [POST /_matrix/client/v3/rooms/knock/{roomIdOrAlias}](https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3knockroomidoralias) From f3ce28bf384ca6cd2cc7077f14da2dfb0d7f05a3 Mon Sep 17 00:00:00 2001 From: Half-Shot Date: Tue, 19 Jul 2022 22:02:11 +0100 Subject: [PATCH 04/10] s/latest/v1.3 --- proposals/3848-errcode-specific-failure.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/proposals/3848-errcode-specific-failure.md b/proposals/3848-errcode-specific-failure.md index 65e841fd5..3a53d839e 100644 --- a/proposals/3848-errcode-specific-failure.md +++ b/proposals/3848-errcode-specific-failure.md @@ -10,25 +10,25 @@ if it tries to invite a user that is already joined. ## Proposal New `errcode` would be introduced into the error body of a response -(https://spec.matrix.org/latest/client-server-api/#standard-error-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 user is already joined to the room. This would cover endpoints: - - [POST /_matrix/client/v3/rooms/{roomId}/invite](https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3roomsroomidinvite) - - [POST /_matrix/client/v3/rooms/knock/{roomIdOrAlias}](https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3knockroomidoralias) - - [PUT /_matrix/client/v3/rooms/{roomId}/state/{eventType}/{stateKey}](https://spec.matrix.org/latest/client-server-api/#put_matrixclientv3roomsroomidstateeventtypestatekey) + - [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 your user does not have the specific required power level to perform an action in the room. - - [POST /_matrix/client/v3/rooms/{roomId}/invite](https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3roomsroomidinvite) - - [POST /_matrix/client/v3/rooms/knock/{roomIdOrAlias}](https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3knockroomidoralias) - - [POST /_matrix/client/v3/rooms/{roomId}/unban](https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3roomsroomidban) - - [POST /_matrix/client/v3/rooms/{roomId}/ban](https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3roomsroomidban) - - [POST /_matrix/client/v3/rooms/{roomId}/kick](https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3roomsroomidkick) - - [PUT /_matrix/client/v3/rooms/{roomId}/state/{eventType}/{stateKey}](https://spec.matrix.org/latest/client-server-api/#put_matrixclientv3roomsroomidstateeventtypestatekey) + - [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) ## Potential issues From 02e7265eb343ee5e997e2a7e9bc242c595e02a75 Mon Sep 17 00:00:00 2001 From: Half-Shot Date: Wed, 20 Jul 2022 18:32:39 +0100 Subject: [PATCH 05/10] add prefix note --- proposals/3848-errcode-specific-failure.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/proposals/3848-errcode-specific-failure.md b/proposals/3848-errcode-specific-failure.md index 3a53d839e..701001178 100644 --- a/proposals/3848-errcode-specific-failure.md +++ b/proposals/3848-errcode-specific-failure.md @@ -53,6 +53,8 @@ While this MSC is not considered stable for implementation, implementations shou 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. \ No newline at end of file From 1dd827cc61b5312945313316425ecbf5d505e076 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Wed, 20 Jul 2022 19:30:51 +0100 Subject: [PATCH 06/10] Reword --- proposals/3848-errcode-specific-failure.md | 34 ++++++++++++++-------- 1 file changed, 22 insertions(+), 12 deletions(-) diff --git a/proposals/3848-errcode-specific-failure.md b/proposals/3848-errcode-specific-failure.md index 701001178..2772a36c1 100644 --- a/proposals/3848-errcode-specific-failure.md +++ b/proposals/3848-errcode-specific-failure.md @@ -1,11 +1,17 @@ -# MSC3848: Introduce errcodes for specific membership change failures. +# MSC3848: Introduce errcodes for specific event sending failures. -When performing an action on the C-S API, sometimes it will fail if the user is -already joined to the room. In these cases, homeservers will throw a `M_FORBIDDEN` -stating that the action wasn't successful. However, it's difficult to distinguish this -kind of failure from insufficient permission errors (or other kinds of errors). This would be -useful, as the caller can then react to the error e.g. refresh it's membership cache -if it tries to invite a user that is already joined. +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 @@ -28,20 +34,24 @@ perform an action in the room. - [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}/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. However, the alternative is keeping -the non-specific error codes and having the +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 it's 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. +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 @@ -57,4 +67,4 @@ The errcodes will be have the prefix `M_` replaced with `ORG.MATRIX.MSC3848.`. ## Dependencies -None. \ No newline at end of file +None. From 4a65135e6a997a6a4032d6e420f8cf98410c2d35 Mon Sep 17 00:00:00 2001 From: Half-Shot Date: Fri, 22 Jul 2022 10:10:36 +0100 Subject: [PATCH 07/10] Add M_NOT_JOINED --- proposals/3848-errcode-specific-failure.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/proposals/3848-errcode-specific-failure.md b/proposals/3848-errcode-specific-failure.md index 2772a36c1..f066c298c 100644 --- a/proposals/3848-errcode-specific-failure.md +++ b/proposals/3848-errcode-specific-failure.md @@ -18,7 +18,7 @@ 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 user +`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) @@ -27,8 +27,11 @@ 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 your user does not have the specific required power level to +`M_INSUFFICIENT_POWER` would be when the authenticated user does not have the specific 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) From 11a299527602c10d7173d7bb4156abf66df460a1 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Mon, 25 Jul 2022 15:08:36 +0100 Subject: [PATCH 08/10] Add namespace to error --- proposals/3848-errcode-specific-failure.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3848-errcode-specific-failure.md b/proposals/3848-errcode-specific-failure.md index f066c298c..4561dafd6 100644 --- a/proposals/3848-errcode-specific-failure.md +++ b/proposals/3848-errcode-specific-failure.md @@ -62,7 +62,7 @@ None. ## Unstable prefix -While this MSC is not considered stable for implementation, implementations should use `org.matrix.unstable.errcode` +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. From 48ff84d14081b44faef52a5ecb3a8d705d9fc563 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Mon, 25 Jul 2022 21:20:32 +0100 Subject: [PATCH 09/10] Spacing --- proposals/3848-errcode-specific-failure.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/proposals/3848-errcode-specific-failure.md b/proposals/3848-errcode-specific-failure.md index 4561dafd6..5790ecb0f 100644 --- a/proposals/3848-errcode-specific-failure.md +++ b/proposals/3848-errcode-specific-failure.md @@ -20,17 +20,21 @@ New `errcode` would be introduced into the error body of a 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 specific 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) From 495b2aeaebb5e428c03ddcb2207cce3476cac234 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Tue, 26 Jul 2022 15:00:11 +0100 Subject: [PATCH 10/10] Apply suggestions from code review Co-authored-by: Christian Paul --- proposals/3848-errcode-specific-failure.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/3848-errcode-specific-failure.md b/proposals/3848-errcode-specific-failure.md index 5790ecb0f..f663ba256 100644 --- a/proposals/3848-errcode-specific-failure.md +++ b/proposals/3848-errcode-specific-failure.md @@ -29,7 +29,7 @@ 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 specific required power level to +`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 @@ -51,7 +51,7 @@ Changing long-established error codes in Matrix will be fraught with risk, as ma 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 it's own field. This gives clients a chance to adapt to 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