This article covers the common error codes you may encounter when using the Mural API. We’ll also explain how to handle these errors, so that you can more easily integrate with our API.

📘

You'll see the word "widgets" throughout this guide. Widgets are the same as objects in Mural. For more information on objects, see our Objects in Mural support article.

Mural uses standard HTTP response codes to indicate success or failure of an API request. Generally speaking:

  • 2xx codes indicate a successful request.
  • 3xx codes indicate redirects.
  • 4xx codes indicate an error with the information the client provided.
  • 5xx codes indicate an error with Mural’s server.

For more information on HTTP status codes, see Mozilla's HTTP response status codes.

Error response format

When the server responds with an error, the response body describes the error using the following format:

{
    "code": "<error code>",
    "message": "<error message>"
}

The value of code is an error code that identifies the error. The value of message is a short, human-readable description of the error.

Mural error codes

Here are some errors you may encounter when using the Mural API, as well as recommended error handling:

Error code 400

MessageDescriptionWhat to do
UNSUPPORTED_WIDGET_TYPEThe operation cannot be performed on this widget type.Check the target widget type and widget ID.
WIDGET_REFERENCE_NOT_FOUNDThe reference widget was not found or is not valid.Check the reference widget.
PAGINATION_INVALIDThe pagination is invalid.Check pagination params.
LIMIT_INVALIDThe limit is invalid.Check the limit (should be positive non-zero value).
NEXT_TOKEN_EXPIREDThe next token has expired or does not exist.Obtain new next token.

Error code 401

MessageDescriptionWhat to do
UNAUTHORIZEDYou don't have the required permissions to access this endpoint.Check your permission level. Enter a valid access token.
TOKEN_EXPIREDYour token has expired. You need to refresh your OAuth token.Get a new access token.

Error code 403

MessageDescriptionWhat to do
MURAL_EDIT_FORBIDDENThe user is not allowed to update a mural in this room.Check your permission level.
MURAL_VIEW_FORBIDDENThe user is not allowed to access this mural.Check your permission level.
MURAL_DELETE_FORBIDDENThe user is not allowed to delete this mural.Check your permission level.
MURAL_CREATE_FORBIDDENThe user is not allowed to create a mural in this room.Check your permission level.
MURAL_CREATE_FORBIDDENThis workspace is part of the Free plan which only allows 5 murals. You can delete a mural to create a new one.Switch to a paid plan or delete an old mural.
MURAL_CHAT_ACCESS_FORBIDDENThe authenticated user does not have access to the requested mural's chat.Check chat ID.
TEMPLATE_SEARCH_FORBIDDENCannot perform a search on this workspace.Check workspace ID.
CUSTOM_TEMPLATE_PUBLISH_FORBIDDENThe user is not allowed to create a custom template from the requested mural.Check your permission level.
MURAL_CREATE_FORBIDDENThe user is not allowed to create a mural in this room.Check your permission level.
CUSTOM_TEMPLATE_PUBLISH_FORBIDDENThe user is not allowed to create a custom template from the requested mural.Check your permission level.
TEMPLATE_REMOVE_FORBIDDENThe user is not allowed to delete the template.Check your permission level.
ROOM_VIEW_FORBIDDENThe logged-in user does not have permission to access this room.Check your permission level.
ROOM_DELETE_FORBIDDENThe logged-in user does not have permission to delete this room.Check your permission level.
ROOM_EDIT_FORBIDDENThe logged-in user is not allowed to update this room.Check your permission level.
WORKSPACE_CREATE_ROOM_FORBIDDENThe user is not allowed to create a room in this workspace.Check your permission level.
WORKSPACE_LIST_ROOMS_FORBIDDENCannot list rooms in this workspace.Check your permission level.
WORKSPACE_VIEW_FORBIDDENThe user is not allowed to access this workspace.Check your permission level.
MURAL_DUPLICATE_FORBIDDENCannot duplicate the mural.Check your permission level.
INVALID_SCOPEThe logged-in user does not have the right scope(s) to access this resource.Check provided scope.
VISITOR_ACCESS_FORBIDDENYou need to create a user account and register an OAuth app from that account in order to use the public API.Create and register user account.
WIDGET_MESSAGE_UPDATE_FORBIDDENOnly the widget's owner can update the message.Check widget ID.
WIDGET_RESOLVED_FORBIDDENThe resolved state can only be set by a facilitator, owner of the widget, or user who has replied.Check your role.
CANNOT_DUPLICATE_CONFIDENTIALA mural from a confidential room cannot be duplicated in another room.Check mural ID, switch room status from confidential to public.
GLOBAL_TEMPLATE_DELETE_FORBIDDENThe user is not allowed to delete a global template.Check your permission level.
ROOM_CANNOT_CREATE_COMPANY_POLICYThe logged-in user does not have permission to create a room because of the settings set in the company dashboard.Check company dashboard settings.
ROOM_CANNOT_CREATE_WORKSPACE_POLICYThe logged-in user does not have permission to create a room because of the settings set by the workspace administrator for the workspace this room is part of.Check the workspace settings.
ROOM_CANNOT_CREATE_CONFIDENTIALThe logged-in user does not have the permission to create a confidential room.Check your permission level and check your plan.
ROOM_CANNOT_CREATE_FREE_PLANCannot create a private or confidential room with a Free plan.Check your plan.
ROOM_EDIT_FORBIDDENThe logged-in user is not allowed to update this room.Check your permission level.
ROOM_CANNOT_EDIT_COMPANY_POLICYThe logged-in user does not have permission to update this room because of the settings set in the company dashboard.Check company dashboard settings.
ROOM_CANNOT_EDIT_WORKSPACE_POLICYThe logged-in user does not have permission to update this room because of the settings set by the workspace administrator for the workspace this room is part of.Check the workspace settings.
ROOM_CANNOT_EDIT_FREE_PLANFree plans cannot change an open room to a private room.Check your plan.
WORKSPACE_CREATE_ROOM_FORBIDDENThe user is not allowed to create a room in this workspace.Check your permission level.
UNSUPPORTED_ZONEDue to a data residency configuration made by your admin, this API endpoint is not supported in this workspace.Check your permission level and check your target endpoint.
WORKSPACE_LIST_OPEN_ROOMS_FORBIDDENCannot list the open rooms in this workspace.Check your permission level.

Error code 404

MessageDescriptionWhat to do
WORKSPACE_NOT_FOUNDThe workspace was not found or does not exist.Check the workspace ID.
MURAL_NOT_FOUNDThe mural was not found or does not exist.Check the mural ID.
ROOM_NOT_FOUNDThe room was not found or does not exist.Check the room ID.
TEMPLATE_NOT_FOUNDThe template was not found or does not exist.Check the template ID.
MEMBER_NOT_FOUNDThe member was not found or does not exist.Check the member ID.
PATH_NOT_FOUNDThe path was not found in our servers. Please view the corresponding documentation of the public API.Check provided Path.
WIDGET_NOT_FOUNDThe widget was not found or does not exist.Check widget ID.
VOTING_SESSION_NOT_FOUNDThe voting session does not exist.Check voting session ID.
TARGET_FOLDER_NOT_FOUNDThe destination folder was not found or does not exist.Check target folder ID.
USER_NOT_FOUNDThe user was not found or does not exist.Check user ID.

Error code 500

MessageDescriptionWhat to do
INTERNAL_SERVER_ERRORAn unexpected condition was encountered that prevented us from fulfilling the request. Please try it again later.If the issue continues or you think it's a bug, please let us know.