diff --git a/changelogs/internal/newsfragments/2323.clarification b/changelogs/internal/newsfragments/2323.clarification new file mode 100644 index 00000000..eebfb6bd --- /dev/null +++ b/changelogs/internal/newsfragments/2323.clarification @@ -0,0 +1 @@ +Render error code sections as definition lists to improve readability. diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 5f74ad40..231c92f9 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -94,50 +94,50 @@ 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. +: Forbidden access, e.g. joining a room without permission, failed login. `M_UNKNOWN_TOKEN` -The access or refresh token specified was not recognised. +: The access or refresh token specified was not recognised. -An additional response parameter, `soft_logout`, might be present on the +: 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. +: 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. +: 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 +: The account has been [suspended](#account-suspension) and can only be used for limited actions at this time. `M_BAD_JSON` -Request contained valid JSON, but it was malformed in some way, e.g. +: 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. +: Request did not contain valid JSON. `M_NOT_FOUND` -No resource was found for this request. +: No resource was found for this request. `M_LIMIT_EXCEEDED` -Too many requests have been sent in a short period of time. Wait a while +: 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 +: 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_UNKNOWN_DEVICE` -{{% added-in v="1.17" %}} The device ID supplied by the application service does +: {{% 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_RESOURCE_LIMIT_EXCEEDED` -The request cannot be completed because the homeserver has reached a +: The request cannot be completed because the homeserver has reached a resource limit imposed on it. For example, a homeserver held in a shared hosting environment may reach a resource limit if it starts using too much memory or disk space. The error MUST have an `admin_contact` field @@ -148,7 +148,7 @@ only read state (e.g.: [`/sync`](#get_matrixclientv3sync), [`/user/{userId}/account_data/{type}`](#get_matrixclientv3useruseridaccount_datatype), etc). `M_UNKNOWN` -An unknown error has occurred. +: An unknown error has occurred. #### Other error codes @@ -157,90 +157,90 @@ The following error codes are specific to certain endpoints. `M_UNAUTHORIZED` -The request was not correctly authorized. Usually due to login failures. +: The request was not correctly authorized. Usually due to login failures. `M_USER_DEACTIVATED` -The user ID associated with the request has been deactivated. Typically +: The user ID associated with the request has been deactivated. Typically for endpoints that prove authentication, such as [`/login`](#get_matrixclientv3login). `M_USER_IN_USE` -Encountered when trying to register a user ID which has been taken. +: Encountered when trying to register a user ID which has been taken. `M_INVALID_USERNAME` -Encountered when trying to register a user ID which is not valid. +: Encountered when trying to register a user ID which is not valid. `M_ROOM_IN_USE` -Sent when the room alias given to the `createRoom` API is already in +: 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. +: 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 +: 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 +: Sent when a threepid given to an API cannot be used because no record matching the threepid was found. `M_THREEPID_AUTH_FAILED` -Authentication could not be performed on the third-party identifier. +: Authentication could not be performed on the third-party identifier. `M_THREEPID_DENIED` -The server does not permit this third-party identifier. This may happen +: The server does not permit this third-party identifier. This may happen 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, +: The client's request used a third-party server, e.g. identity server, that this server does not trust. `M_UNSUPPORTED_ROOM_VERSION` -The client's request to create a room used a room version that the +: 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 +: 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_BAD_STATE` -The state change requested cannot be performed, such as attempting to +: The state change requested cannot be performed, such as attempting to unban a user who is not banned. `M_GUEST_ACCESS_FORBIDDEN` -The room or resource does not permit guests to access it. +: The room or resource does not permit guests to access it. `M_CAPTCHA_NEEDED` -A Captcha is required to complete the request. +: A Captcha is required to complete the request. `M_CAPTCHA_INVALID` -The Captcha provided did not match what was expected. +: The Captcha provided did not match what was expected. `M_MISSING_PARAM` -A required parameter was missing from the request. +: A required parameter was missing from the request. `M_INVALID_PARAM` -A parameter that was specified has the wrong value. For example, the +: 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. +: The request or entity was too large. `M_EXCLUSIVE` -The resource being requested is reserved by an application service, or +: 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. +: 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. +: 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 +: The third party identifier specified by the client is not acceptable because it is already in use in some way. #### Rate limiting diff --git a/content/identity-service-api.md b/content/identity-service-api.md index 8946ad34..89fb486d 100644 --- a/content/identity-service-api.md +++ b/content/identity-service-api.md @@ -71,53 +71,53 @@ 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. +: The resource requested could not be located. `M_MISSING_PARAMS` -The request was missing one or more parameters. +: The request was missing one or more parameters. `M_INVALID_PARAM` -The request contained one or more invalid parameters. +: The request contained one or more invalid parameters. `M_SESSION_NOT_VALIDATED` -The session has not been validated. +: The session has not been validated. `M_NO_VALID_SESSION` -A session could not be located for the given parameters. +: A session could not be located for the given parameters. `M_SESSION_EXPIRED` -The session has expired and must be renewed. +: The session has expired and must be renewed. `M_INVALID_EMAIL` -The email address provided was not valid. +: The email address provided was not valid. `M_EMAIL_SEND_ERROR` -There was an error sending an email. Typically seen when attempting to +: There was an error sending an email. Typically seen when attempting to verify ownership of a given email address. `M_INVALID_ADDRESS` -The provided third-party address was not valid. +: The provided third-party address was not valid. `M_SEND_ERROR` -There was an error sending a notification. Typically seen when +: There was an error sending a notification. Typically seen when attempting to verify ownership of a given third-party address. `M_UNRECOGNIZED` -The request contained an unrecognised value, such as an unknown token or +: The request contained an unrecognised value, such as an unknown token or medium. -This is also used as the response if a server did not understand the request. +: This is also used as the response if a 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_THREEPID_IN_USE` -The third-party identifier is already in use by another user. Typically +: 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. +: An unknown error has occurred. ## Privacy