Errors

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

Message	Description	What to do
UNSUPPORTED_WIDGET_TYPE	The operation cannot be performed on this widget type.	Check the target widget type and widget ID.
WIDGET_REFERENCE_NOT_FOUND	The reference widget was not found or is not valid.	Check the reference widget.
PAGINATION_INVALID	The pagination is invalid.	Check pagination params.
LIMIT_INVALID	The limit is invalid.	Check the limit (should be positive non-zero value).
NEXT_TOKEN_EXPIRED	The next token has expired or does not exist.	Obtain new next token.

Error code 401

Message	Description	What to do
UNAUTHORIZED	You don't have the required permissions to access this endpoint.	Check your permission level. Enter a valid access token.
TOKEN_EXPIRED	Your token has expired. You need to refresh your OAuth token.	Get a new access token.

Error code 403

Message	Description	What to do
MURAL_EDIT_FORBIDDEN	The user is not allowed to update a mural in this room.	Check your permission level.
MURAL_VIEW_FORBIDDEN	The user is not allowed to access this mural.	Check your permission level.
MURAL_DELETE_FORBIDDEN	The user is not allowed to delete this mural.	Check your permission level.
MURAL_CREATE_FORBIDDEN	The user is not allowed to create a mural in this room.	Check your permission level.
MURAL_CREATE_FORBIDDEN	This 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_FORBIDDEN	The authenticated user does not have access to the requested mural's chat.	Check chat ID.
TEMPLATE_SEARCH_FORBIDDEN	Cannot perform a search on this workspace.	Check workspace ID.
CUSTOM_TEMPLATE_PUBLISH_FORBIDDEN	The user is not allowed to create a custom template from the requested mural.	Check your permission level.
MURAL_CREATE_FORBIDDEN	The user is not allowed to create a mural in this room.	Check your permission level.
CUSTOM_TEMPLATE_PUBLISH_FORBIDDEN	The user is not allowed to create a custom template from the requested mural.	Check your permission level.
TEMPLATE_REMOVE_FORBIDDEN	The user is not allowed to delete the template.	Check your permission level.
ROOM_VIEW_FORBIDDEN	The logged-in user does not have permission to access this room.	Check your permission level.
ROOM_DELETE_FORBIDDEN	The logged-in user does not have permission to delete this room.	Check your permission level.
ROOM_EDIT_FORBIDDEN	The logged-in user is not allowed to update this room.	Check your permission level.
WORKSPACE_CREATE_ROOM_FORBIDDEN	The user is not allowed to create a room in this workspace.	Check your permission level.
WORKSPACE_LIST_ROOMS_FORBIDDEN	Cannot list rooms in this workspace.	Check your permission level.
WORKSPACE_VIEW_FORBIDDEN	The user is not allowed to access this workspace.	Check your permission level.
MURAL_DUPLICATE_FORBIDDEN	Cannot duplicate the mural.	Check your permission level.
INVALID_SCOPE	The logged-in user does not have the right scope(s) to access this resource.	Check provided scope.
VISITOR_ACCESS_FORBIDDEN	You 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_FORBIDDEN	Only the widget's owner can update the message.	Check widget ID.
WIDGET_RESOLVED_FORBIDDEN	The resolved state can only be set by a facilitator, owner of the widget, or user who has replied.	Check your role.
CANNOT_DUPLICATE_CONFIDENTIAL	A mural from a confidential room cannot be duplicated in another room.	Check mural ID, switch room status from confidential to public.
GLOBAL_TEMPLATE_DELETE_FORBIDDEN	The user is not allowed to delete a global template.	Check your permission level.
ROOM_CANNOT_CREATE_COMPANY_POLICY	The 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_POLICY	The 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_CONFIDENTIAL	The 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_PLAN	Cannot create a private or confidential room with a Free plan.	Check your plan.
ROOM_EDIT_FORBIDDEN	The logged-in user is not allowed to update this room.	Check your permission level.
ROOM_CANNOT_EDIT_COMPANY_POLICY	The 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_POLICY	The 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_PLAN	Free plans cannot change an open room to a private room.	Check your plan.
WORKSPACE_CREATE_ROOM_FORBIDDEN	The user is not allowed to create a room in this workspace.	Check your permission level.
UNSUPPORTED_ZONE	Due 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_FORBIDDEN	Cannot list the open rooms in this workspace.	Check your permission level.

Error code 404

Message	Description	What to do
WORKSPACE_NOT_FOUND	The workspace was not found or does not exist.	Check the workspace ID.
MURAL_NOT_FOUND	The mural was not found or does not exist.	Check the mural ID.
ROOM_NOT_FOUND	The room was not found or does not exist.	Check the room ID.
TEMPLATE_NOT_FOUND	The template was not found or does not exist.	Check the template ID.
MEMBER_NOT_FOUND	The member was not found or does not exist.	Check the member ID.
PATH_NOT_FOUND	The path was not found in our servers. Please view the corresponding documentation of the public API.	Check provided Path.
WIDGET_NOT_FOUND	The widget was not found or does not exist.	Check widget ID.
VOTING_SESSION_NOT_FOUND	The voting session does not exist.	Check voting session ID.
TARGET_FOLDER_NOT_FOUND	The destination folder was not found or does not exist.	Check target folder ID.
USER_NOT_FOUND	The user was not found or does not exist.	Check user ID.

Error code 500

Message	Description	What to do
INTERNAL_SERVER_ERROR	An 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.