Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-03-18 09:24:10 +01:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Order error codes and remove duplicate M_THREEPID_IN_USE definition (#2336)
Some checks are pending
Spec / 🔎 Validate OpenAPI specifications (push) Waiting to run
Details
Spec / 🔎 Check Event schema examples (push) Waiting to run
Details
Spec / 🔎 Check OpenAPI definitions examples (push) Waiting to run
Details
Spec / 🔎 Check JSON Schemas inline examples (push) Waiting to run
Details
Spec / ⚙️ Calculate baseURL for later jobs (push) Waiting to run
Details
Spec / 🐍 Build OpenAPI definitions (push) Blocked by required conditions
Details
Spec / 📢 Run towncrier for changelog (push) Waiting to run
Details
Spec / 📖 Build the spec (push) Blocked by required conditions
Details
Spec / 🔎 Validate generated HTML (push) Blocked by required conditions
Details
Spec / 📖 Build the historical backup spec (push) Blocked by required conditions
Details
Spec / Create release (push) Blocked by required conditions
Details
Spell Check / Spell Check with Typos (push) Waiting to run
Details

Browse source 
* Order error codes alphabetically

* Remove duplicated definition of M_THREEPID_IN_USE

* Changelog

* With inline comments about keeping them ordered
This commit is contained in:
Hugh Nimmo-Smith 2026-03-17 17:35:06 +00:00 committed by GitHub
parent 4f079f8a9c
commit 3e1cbe12f7
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 128 additions and 118 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
changelogs/client_server/newsfragments/2336.clarification Normal file
View file

@ -0,0 +1 @@
Order the common and other error codes alphabetically and remove duplicate `M_THREEPID_IN_USE` definition.

1
changelogs/identity_service/newsfragments/2336.clarification Normal file
View file

@ -0,0 +1 @@
Order the standard error codes alphabetically.

186
content/client-server-api/_index.md
View file

@ -93,48 +93,27 @@ request being made was invalid.
These error codes can be returned by any API endpoint:
`M_FORBIDDEN`
: Forbidden access, e.g. joining a room without permission, failed login.
`M_UNKNOWN_TOKEN`
: The access or refresh token specified was not recognised.
: An additional response parameter, `soft_logout`, might be present on the
response for 401 HTTP status codes. See [the soft logout
section](#soft-logout) for more information.
`M_MISSING_TOKEN`
: No access token was specified for the request.
`M_USER_LOCKED`
: The account has been [locked](#account-locking) and cannot be used at this time.
`M_USER_SUSPENDED`
: The account has been [suspended](#account-suspension) and can only be used for
limited actions at this time.
<!-- Please keep the error codes below in alphabetical order -->
`M_BAD_JSON`
: Request contained valid JSON, but it was malformed in some way, e.g.
missing required keys, invalid values for keys.
`M_NOT_JSON`
: Request did not contain valid JSON.
`M_NOT_FOUND`
: No resource was found for this request.
`M_FORBIDDEN`
: Forbidden access, e.g. joining a room without permission, failed login.
`M_LIMIT_EXCEEDED`
: Too many requests have been sent in a short period of time. Wait a while
then try again. See [Rate limiting](#rate-limiting).
`M_UNRECOGNIZED`
: The server did not understand the request. This is expected to be returned with
a 404 HTTP status code if the endpoint is not implemented or a 405 HTTP status
code if the endpoint is implemented, but the incorrect HTTP method is used.
`M_MISSING_TOKEN`
: No access token was specified for the request.
`M_UNKNOWN_DEVICE`
: {{% added-in v="1.17" %}} The device ID supplied by the application service does
not belong to the user ID during [identity assertion](/application-service-api/#identity-assertion).
`M_NOT_FOUND`
: No resource was found for this request.
`M_NOT_JSON`
: Request did not contain valid JSON.
`M_RESOURCE_LIMIT_EXCEEDED`
: The request cannot be completed because the homeserver has reached a
@ -181,39 +160,85 @@ limit is a hard limit that cannot be increased.
`M_UNKNOWN`
: An unknown error has occurred.
`M_UNKNOWN_DEVICE`
: {{% added-in v="1.17" %}} The device ID supplied by the application service does
not belong to the user ID during [identity assertion](/application-service-api/#identity-assertion).
`M_UNKNOWN_TOKEN`
: The access or refresh token specified was not recognised.
: An additional response parameter, `soft_logout`, might be present on the
response for 401 HTTP status codes. See [the soft logout
section](#soft-logout) for more information.
`M_UNRECOGNIZED`
: The server did not understand the request. This is expected to be returned with
a 404 HTTP status code if the endpoint is not implemented or a 405 HTTP status
code if the endpoint is implemented, but the incorrect HTTP method is used.
`M_USER_LOCKED`
: The account has been [locked](#account-locking) and cannot be used at this time.
`M_USER_SUSPENDED`
: The account has been [suspended](#account-suspension) and can only be used for
limited actions at this time.
<!-- Please keep the error codes above in alphabetical order -->
#### Other error codes
The following error codes are specific to certain endpoints.
<!-- TODO: move them to the endpoints that return them -->
`M_UNAUTHORIZED`
: The request was not correctly authorized. Usually due to login failures.
<!-- Please keep the error codes below in alphabetical order -->
`M_USER_DEACTIVATED`
: The user ID associated with the request has been deactivated. Typically
for endpoints that prove authentication, such as [`/login`](#get_matrixclientv3login).
`M_BAD_STATE`
: The state change requested cannot be performed, such as attempting to
unban a user who is not banned.
`M_USER_IN_USE`
: Encountered when trying to register a user ID which has been taken.
`M_CANNOT_LEAVE_SERVER_NOTICE_ROOM`
: The user is unable to reject an invite to join the server notices room.
See the [Server Notices](#server-notices) module for more information.
`M_CAPTCHA_INVALID`
: The Captcha provided did not match what was expected.
`M_CAPTCHA_NEEDED`
: A Captcha is required to complete the request.
`M_EXCLUSIVE`
: The resource being requested is reserved by an application service, or
the application service making the request has not created the resource.
`M_GUEST_ACCESS_FORBIDDEN`
: The room or resource does not permit guests to access it.
`M_INCOMPATIBLE_ROOM_VERSION`
: The client attempted to join a room that has a version the server does
not support. Inspect the `room_version` property of the error response
for the room's version.
`M_INVALID_PARAM`
: A parameter that was specified has the wrong value. For example, the
server expected an integer and instead received a string.
`M_INVALID_ROOM_STATE`
: Sent when the initial state given to the `createRoom` API is invalid.
`M_INVALID_USERNAME`
: Encountered when trying to register a user ID which is not valid.
`M_MISSING_PARAM`
: A required parameter was missing from the request.
`M_ROOM_IN_USE`
: Sent when the room alias given to the `createRoom` API is already in
use.
`M_INVALID_ROOM_STATE`
: Sent when the initial state given to the `createRoom` API is invalid.
`M_THREEPID_IN_USE`
: Sent when a threepid given to an API cannot be used because the same
threepid is already in use.
`M_THREEPID_NOT_FOUND`
: Sent when a threepid given to an API cannot be used because no record
matching the threepid was found.
`M_SERVER_NOT_TRUSTED`
: The client's request used a third-party server, e.g. identity server,
that this server does not trust.
`M_THREEPID_AUTH_FAILED`
: Authentication could not be performed on the third-party identifier.
@ -223,56 +248,35 @@ matching the threepid was found.
if the server only permits, for example, email addresses from a
particular domain.
`M_SERVER_NOT_TRUSTED`
: The client's request used a third-party server, e.g. identity server,
that this server does not trust.
`M_THREEPID_IN_USE`
: The third party identifier specified by the client is not acceptable because it is
already in use in some way.
`M_THREEPID_MEDIUM_NOT_SUPPORTED`
: The homeserver does not support adding a third party identifier of the given medium.
`M_THREEPID_NOT_FOUND`
: Sent when a threepid given to an API cannot be used because no record
matching the threepid was found.
`M_TOO_LARGE`
: The request or entity was too large.
`M_UNAUTHORIZED`
: The request was not correctly authorized. Usually due to login failures.
`M_UNSUPPORTED_ROOM_VERSION`
: The client's request to create a room used a room version that the
server does not support.
`M_INCOMPATIBLE_ROOM_VERSION`
: The client attempted to join a room that has a version the server does
not support. Inspect the `room_version` property of the error response
for the room's version.
`M_USER_DEACTIVATED`
: The user ID associated with the request has been deactivated. Typically
for endpoints that prove authentication, such as [`/login`](#get_matrixclientv3login).
`M_BAD_STATE`
: The state change requested cannot be performed, such as attempting to
unban a user who is not banned.
`M_USER_IN_USE`
: Encountered when trying to register a user ID which has been taken.
`M_GUEST_ACCESS_FORBIDDEN`
: The room or resource does not permit guests to access it.
`M_CAPTCHA_NEEDED`
: A Captcha is required to complete the request.
`M_CAPTCHA_INVALID`
: The Captcha provided did not match what was expected.
`M_MISSING_PARAM`
: A required parameter was missing from the request.
`M_INVALID_PARAM`
: A parameter that was specified has the wrong value. For example, the
server expected an integer and instead received a string.
`M_TOO_LARGE`
: The request or entity was too large.
`M_EXCLUSIVE`
: The resource being requested is reserved by an application service, or
the application service making the request has not created the resource.
`M_CANNOT_LEAVE_SERVER_NOTICE_ROOM`
: The user is unable to reject an invite to join the server notices room.
See the [Server Notices](#server-notices) module for more information.
`M_THREEPID_MEDIUM_NOT_SUPPORTED`
: The homeserver does not support adding a third party identifier of the given medium.
`M_THREEPID_IN_USE`
: The third party identifier specified by the client is not acceptable because it is
already in use in some way.
<!-- Please keep the error codes above in alphabetical order -->
#### Rate limiting

58
content/identity-service-api.md
View file

@ -70,26 +70,7 @@ the keys `error` and `errcode` MUST always be present.
Some standard error codes are below:
`M_NOT_FOUND`
: The resource requested could not be located.
`M_MISSING_PARAMS`
: The request was missing one or more parameters.
`M_INVALID_PARAM`
: The request contained one or more invalid parameters.
`M_SESSION_NOT_VALIDATED`
: The session has not been validated.
`M_NO_VALID_SESSION`
: A session could not be located for the given parameters.
`M_SESSION_EXPIRED`
: The session has expired and must be renewed.
`M_INVALID_EMAIL`
: The email address provided was not valid.
<!-- Please keep the error codes below in alphabetical order -->
`M_EMAIL_SEND_ERROR`
: There was an error sending an email. Typically seen when attempting to
@ -98,10 +79,39 @@ verify ownership of a given email address.
`M_INVALID_ADDRESS`
: The provided third-party address was not valid.
`M_INVALID_EMAIL`
: The email address provided was not valid.
`M_INVALID_PARAM`
: The request contained one or more invalid parameters.
`M_MISSING_PARAMS`
: The request was missing one or more parameters.
`M_NO_VALID_SESSION`
: A session could not be located for the given parameters.
`M_NOT_FOUND`
: The resource requested could not be located.
`M_SEND_ERROR`
: There was an error sending a notification. Typically seen when
attempting to verify ownership of a given third-party address.
`M_SESSION_EXPIRED`
: The session has expired and must be renewed.
`M_SESSION_NOT_VALIDATED`
: The session has not been validated.
`M_THREEPID_IN_USE`
: The third-party identifier is already in use by another user. Typically
this error will have an additional `mxid` property to indicate who owns
the third-party identifier.
`M_UNKNOWN`
: An unknown error has occurred.
`M_UNRECOGNIZED`
: The request contained an unrecognised value, such as an unknown token or
medium.
@ -111,13 +121,7 @@ This is expected to be returned with a 404 HTTP status code if the endpoint is
not implemented or a 405 HTTP status code if the endpoint is implemented, but
the incorrect HTTP method is used.
`M_THREEPID_IN_USE`
: The third-party identifier is already in use by another user. Typically
this error will have an additional `mxid` property to indicate who owns
the third-party identifier.
`M_UNKNOWN`
: An unknown error has occurred.
<!-- Please keep the error codes above in alphabetical order -->
## Privacy