synapse.api.errors module

Contains exceptions and error codes.

exception synapse.api.errors.AuthError(*args, **kwargs)

Bases: synapse.api.errors.SynapseError

An error raised when there was a problem authorising an event, and at various other poorly-defined times.

exception synapse.api.errors.CodeMessageException(code, msg)

Bases: RuntimeError

An exception with integer code and message string attributes.

Variables
  • code (int) – HTTP error code

  • msg (str) – string describing the error

class synapse.api.errors.Codes

Bases: object

BAD_JSON = 'M_BAD_JSON'
BAD_PAGINATION = 'M_BAD_PAGINATION'
BAD_STATE = 'M_BAD_STATE'
CANNOT_LEAVE_SERVER_NOTICE_ROOM = 'M_CANNOT_LEAVE_SERVER_NOTICE_ROOM'
CAPTCHA_INVALID = 'M_CAPTCHA_INVALID'
CAPTCHA_NEEDED = 'M_CAPTCHA_NEEDED'
CONSENT_NOT_GIVEN = 'M_CONSENT_NOT_GIVEN'
EXCLUSIVE = 'M_EXCLUSIVE'
EXPIRED_ACCOUNT = 'ORG_MATRIX_EXPIRED_ACCOUNT'
FORBIDDEN = 'M_FORBIDDEN'
GUEST_ACCESS_FORBIDDEN = 'M_GUEST_ACCESS_FORBIDDEN'
INCOMPATIBLE_ROOM_VERSION = 'M_INCOMPATIBLE_ROOM_VERSION'
INVALID_PARAM = 'M_INVALID_PARAM'
INVALID_SIGNATURE = 'M_INVALID_SIGNATURE'
INVALID_USERNAME = 'M_INVALID_USERNAME'
LIMIT_EXCEEDED = 'M_LIMIT_EXCEEDED'
MISSING_PARAM = 'M_MISSING_PARAM'
MISSING_TOKEN = 'M_MISSING_TOKEN'
NOT_FOUND = 'M_NOT_FOUND'
NOT_JSON = 'M_NOT_JSON'
RESOURCE_LIMIT_EXCEEDED = 'M_RESOURCE_LIMIT_EXCEEDED'
ROOM_IN_USE = 'M_ROOM_IN_USE'
SERVER_NOT_TRUSTED = 'M_SERVER_NOT_TRUSTED'
THREEPID_AUTH_FAILED = 'M_THREEPID_AUTH_FAILED'
THREEPID_DENIED = 'M_THREEPID_DENIED'
THREEPID_IN_USE = 'M_THREEPID_IN_USE'
THREEPID_NOT_FOUND = 'M_THREEPID_NOT_FOUND'
TOO_LARGE = 'M_TOO_LARGE'
UNAUTHORIZED = 'M_UNAUTHORIZED'
UNKNOWN = 'M_UNKNOWN'
UNKNOWN_TOKEN = 'M_UNKNOWN_TOKEN'
UNRECOGNIZED = 'M_UNRECOGNIZED'
UNSUPPORTED_ROOM_VERSION = 'M_UNSUPPORTED_ROOM_VERSION'
USER_DEACTIVATED = 'M_USER_DEACTIVATED'
USER_IN_USE = 'M_USER_IN_USE'
WRONG_ROOM_KEYS_VERSION = 'M_WRONG_ROOM_KEYS_VERSION'
exception synapse.api.errors.ConsentNotGivenError(msg, consent_uri)

Bases: synapse.api.errors.SynapseError

The error returned to the client when the user has not consented to the privacy policy.

error_dict()
exception synapse.api.errors.EventSizeError(*args, **kwargs)

Bases: synapse.api.errors.SynapseError

An error raised when an event is too big.

exception synapse.api.errors.EventStreamError(*args, **kwargs)

Bases: synapse.api.errors.SynapseError

An error raised when there a problem with the event stream.

exception synapse.api.errors.FederationDeniedError(destination)

Bases: synapse.api.errors.SynapseError

An error raised when the server tries to federate with a server which is not on its federation whitelist.

Variables

destination (str) – The destination which has been denied

exception synapse.api.errors.FederationError(level, code, reason, affected, source=None)

Bases: RuntimeError

This class is used to inform remote homeservers about erroneous PDUs they sent us.

FATAL: The remote server could not interpret the source event.

(e.g., it was missing a required field)

ERROR: The remote server interpreted the event, but it failed some other

check (e.g. auth)

WARN: The remote server accepted the event, but believes some part of it

is wrong (e.g., it referred to an invalid event)

get_dict()
exception synapse.api.errors.HttpResponseException(code, msg, response)

Bases: synapse.api.errors.CodeMessageException

Represents an HTTP-level failure of an outbound request

Variables

response (bytes) – body of response

to_synapse_error()

Make a SynapseError based on an HTTPResponseException

This is useful when a proxied request has failed, and we need to decide how to map the failure onto a matrix error to send back to the client.

An attempt is made to parse the body of the http response as a matrix error. If that succeeds, the errcode and error message from the body are used as the errcode and error message in the new synapse error.

Otherwise, the errcode is set to M_UNKNOWN, and the error message is set to the reason code from the HTTP response.

Returns

Return type

SynapseError

exception synapse.api.errors.IncompatibleRoomVersionError(room_version)

Bases: synapse.api.errors.SynapseError

A server is trying to join a room whose version it does not support.

Unlike UnsupportedRoomVersionError, it is specific to the case of the make_join failing.

error_dict()
exception synapse.api.errors.InteractiveAuthIncompleteError(result)

Bases: Exception

An error raised when UI auth is not yet complete

(This indicates we should return a 401 with ‘result’ as the body)

Variables

result (dict) – the server response to the request, which should be passed back to the client

exception synapse.api.errors.InvalidCaptchaError(code=400, msg='Invalid captcha.', error_url=None, errcode='M_CAPTCHA_INVALID')

Bases: synapse.api.errors.SynapseError

error_dict()
exception synapse.api.errors.InvalidClientCredentialsError(msg, errcode)

Bases: synapse.api.errors.SynapseError

An error raised when there was a problem with the authorisation credentials in a client request.

https://matrix.org/docs/spec/client_server/r0.5.0#using-access-tokens:

When credentials are required but missing or invalid, the HTTP call will return with a status of 401 and the error code, M_MISSING_TOKEN or M_UNKNOWN_TOKEN respectively.

exception synapse.api.errors.InvalidClientTokenError(msg='Unrecognised access token', soft_logout=False)

Bases: synapse.api.errors.InvalidClientCredentialsError

Raised when we didn’t understand the access token in a request

error_dict()
exception synapse.api.errors.LimitExceededError(code=429, msg='Too Many Requests', retry_after_ms=None, errcode='M_LIMIT_EXCEEDED')

Bases: synapse.api.errors.SynapseError

A client has sent too many requests and is being throttled.

error_dict()
exception synapse.api.errors.LoginError(code, msg, errcode='M_UNKNOWN')

Bases: synapse.api.errors.SynapseError

An error raised when there was a problem logging in.

exception synapse.api.errors.MissingClientTokenError(msg='Missing access token')

Bases: synapse.api.errors.InvalidClientCredentialsError

Raised when we couldn’t find the access token in a request

exception synapse.api.errors.NotFoundError(msg='Not found', errcode='M_NOT_FOUND')

Bases: synapse.api.errors.SynapseError

An error indicating we can’t find the thing you asked for

exception synapse.api.errors.ProxiedRequestError(code, msg, errcode='M_UNKNOWN', additional_fields=None)

Bases: synapse.api.errors.SynapseError

An error from a general matrix endpoint, eg. from a proxied Matrix API call.

Variables

errcode (str) – Matrix error code e.g ‘M_FORBIDDEN’

error_dict()
exception synapse.api.errors.RedirectException(location: bytes, http_code: int = 302)

Bases: synapse.api.errors.CodeMessageException

A pseudo-error indicating that we want to redirect the client to a different location

Variables

cookies – a list of set-cookies values to add to the response. For example: b”sessionId=a3fWa; Expires=Wed, 21 Oct 2015 07:28:00 GMT”

exception synapse.api.errors.RequestSendFailed(inner_exception, can_retry)

Bases: RuntimeError

Sending a HTTP request over federation failed due to not being able to talk to the remote server for some reason.

This exception is used to differentiate “expected” errors that arise due to networking (e.g. DNS failures, connection timeouts etc), versus unexpected errors (like programming errors).

exception synapse.api.errors.ResourceLimitError(code, msg, errcode='M_RESOURCE_LIMIT_EXCEEDED', admin_contact=None, limit_type=None)

Bases: synapse.api.errors.SynapseError

Any error raised when there is a problem with resource usage. For instance, the monthly active user limit for the server has been exceeded

error_dict()
exception synapse.api.errors.RoomKeysVersionError(current_version)

Bases: synapse.api.errors.SynapseError

A client has tried to upload to a non-current version of the room_keys store

exception synapse.api.errors.StoreError(code, msg, errcode='M_UNKNOWN')

Bases: synapse.api.errors.SynapseError

An error raised when there was a problem storing some data.

exception synapse.api.errors.SynapseError(code, msg, errcode='M_UNKNOWN')

Bases: synapse.api.errors.CodeMessageException

A base exception type for matrix errors which have an errcode and error message (as well as an HTTP status code).

Variables

errcode (str) – Matrix error code e.g ‘M_FORBIDDEN’

error_dict()
exception synapse.api.errors.ThreepidValidationError(*args, **kwargs)

Bases: synapse.api.errors.SynapseError

An error raised when there was a problem authorising an event.

exception synapse.api.errors.UnrecognizedRequestError(*args, **kwargs)

Bases: synapse.api.errors.SynapseError

An error indicating we don’t understand the request you’re trying to make

exception synapse.api.errors.UnsupportedRoomVersionError

Bases: synapse.api.errors.SynapseError

The client’s request to create a room used a room version that the server does not support.

exception synapse.api.errors.UserDeactivatedError(msg)

Bases: synapse.api.errors.SynapseError

The error returned to the client when the user attempted to access an authenticated endpoint, but the account has been deactivated.

synapse.api.errors.cs_error(msg, code='M_UNKNOWN', **kwargs)

Utility method for constructing an error response for client-server interactions.

Parameters
  • msg (str) – The error message.

  • code (str) – The error code.

  • kwargs – Additional keys to add to the response.

Returns

A dict representing the error response JSON.