Log In

Error Handling

This documentation outlines error patterns, provides debugging tips, and lists all possible errors for quick troubleshooting, to aid developers in building resilient applications. This guide aims to streamline issue identification and resolution, ensuring applications gracefully handle errors and maintain a seamless user experience.

Error patterns

The Designer API employs a structured format for exceptions, ensuring you have clear and actionable information at your disposal. Here's what you can expect in the event of an error:

Cause Tag: ResourceRemovalFailed
Message: "Failed to remove style. Ensure there are no usages of this style."

Message (err.message): A descriptive sentence designed to provide immediate insight into what went wrong. The wording of this message may change over time to enhance clarity or reflect updated functionalities within the Designer API. The primary goal of the message field is to guide developers in identifying the source or nature of the failure.

Cause Tag (err.cause.tag): Accompanying each error message is a consistent, unchanging Cause Tag. These tags are your key to handling errors programmatically. They are crafted to enable developers to programmatically distinguish between different error scenarios and respond accordingly.

List of errors

This section provides a detailed list of error cause tags you might encounter while interacting with the Designer API. For each error, you'll receive a specific message tailored to the scenario, designed to give you clarity on the nature of the problem. This list is intended to help you quickly understand the cause of any issues you face.

Cause TagDescription
DuplicateValueIndicates a value was duplicated where it should be unique.
ForbiddenIndicates that a User and/or App doesn't have the permission to take a specific action. For more on this error see documentation on App Modes
InternalErrorAn error occurred within the system or process.
InvalidElementPlacementAn element was placed in an invalid location or context.
InvalidRequestA request is invalid based on the designer's current ability
InvalidStyleThe specified style is invalid or not recognized.
InvalidStyleNameThe specified style name does not exist or is incorrect.
InvalidStylePropertyThe property of the style is invalid or not applicable.
InvalidStyleVariantThe variant of the style specified is invalid or not recognized.
InvalidTargetElementThe target element for the operation is invalid.
PageCreateFailedFailed to create a page due to an unspecified error.
ResourceCreationFailedFailed to create a resource due to an unspecified error.
ResourceMissingThe requested resource is missing or unavailable.
VariableInvalidA variable's value is invalid or not within the expected range.

How to handle errors

Apps need to gracefully manage errors to maintain a seamless user experience, even amid unexpected issues. Please ensure your approach to error handling is comprehensive, capable of detecting and managing exceptions, and offers users a clear pathway to resolution.

Using try/catch for error handling

The try/catch block is seamlessly integrated with async/await syntax, offering a straightforward way to catch exceptions as demonstrated:

  try {
    const element = await webflow.getSelectedElement();
    await element.remove();
    // Attempting further operations on the removed element will throw an error
    const styles = await element.getStyles();
  } catch (err) {

Notifying users of an error

By utilizing the webflow.notify method, you can send a notification directly to the user within the Designer that acknowledges the error and also, when feasible, provides guidance on resolving it. This proactive approach helps maintain trust and ensures users aren't left in the dark, improving their overall experience and satisfaction with your application.

function handleErrors(err) {
  switch (err.cause.tag) {
    case 'ResourceMissing':
      webflow.notify({ type: 'Error', message: 'The element no longer exists.' });
    case 'InvalidElementPlacement':
      // Handle specific error
    // Additional error cases