Exception handling in the API

Exceptions over websockets

In response to an RPC call, instead of returning a response, you might get an exception. For this purpose we use the WAMP message type CALLERROR, which looks as follows:

[4, callID, "http://domain/exceptions#ExceptionType", message]
[4, callID, "http://domain/exceptions#ExceptionType", message, details]

It might also happen that an error condition happens which is not handled on the server at all, in which case the returned exception frame looks like this:

[4, "ce6th2qed7j", "An error occurred."]

Exceptions over HTTP

When using HTTP to call RPC methods, in case of a known exception, the status code in the HTTP response is 400, and the response payload is a JSON object with the following attributes:

  • type

  • message

If a completely unexpected error happens, the HTTP response is just a 400 with Bad Request as the payload.

class instant.exceptions.UserException(name, message, data=None)

RPC exceptions consisting of the machine-readable CamelCase exception name, a human-readable error message, and an optional object with any additional details depending on the type of exception.

Exceptions should follow the following rules:

  1. messages are user friendly

  2. messages are translated on the server side

  3. exceptions not do not expose implementation details of the backend

The following types of exceptions are currently in use by the backend:

DEFAULT_TEAM_RESTRICTION = 'DefaultTeamRoomRestriction'
FORWARD_VALIDATION_ERROR = 'ForwardValidationError'
INVALID_OPERATION = 'InvalidOperation'
MANAGED_ROOMS_RESTRICTION = 'ManagedRoomsRestriction'
MESSAGE_EDIT_TIMEOUT_EXCEEDED = 'MessageEditTimeoutExceeded'

Raised when trying to edit or delete a message when it’s no longer possible.

MISSING_PARAMETERS = 'MissingParameter'
NOT_AUTHORIZED = 'NotAuthorized'

Raised whenever a user does not have sufficient privileges to perform a certain action.

NOT_FOUND_ERROR = 'NotFoundError'

Raised whenever an operation is requested on an object that doesn’t exist.

OUT_OF_RANGE_ERROR = 'OutOfRangeError'
SESSION_ERROR = 'SessionError'
UNKNOWN_ERROR = 'UnknownError'