Handling errors

How to handle errors thrown by the Canva Developers SDK.

In the Canva Developers SDK, all methods have the potential to throw an error if something goes wrong, such as a request timing out or the user being disconnected from the internet.

While developing an app, it's important to:

Be mindful of errors that may occur.
Handle errors as gracefully as possible.

Check out the Error design guidelines

Our design guidelines help you create a high-quality app that easily passes app review.

How to handle errors

Import CanvaError from the @canva/error package:
```
import { CanvaError } from "@canva/error";
```
TS

When calling a method from the Developers SDK, wrap it in a try/catch block:

import { addElementAtPoint } from "@canva/design";
import { CanvaError } from "@canva/error";

try {
  await addElementAtPoint({
    type: "embed",
    url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  });
} catch (error) {
  console.log(error);
}

In the catch block, check if the error is an instance of a CanvaError:
```
if (error instanceof CanvaError) {
  console.log("CanvaError:", error.code);
}
```
TS
The CanvaError object contains two properties:
- code - A string that identifies the reason for the error.
- message - Additional information about the error.

Use the code property to handle the possible error cases:

if (error instanceof CanvaError) {
  switch (error.code) {
    case "permission_denied":
      console.log("You don't have the required permissions.");
      break;
    case "user_offline":
      console.log("You're offline.");
      break;
    case "timeout":
      console.log("The request timed out.");
      break;
  }
}

You don't have to handle all error codes for all methods — most methods only have the potential to throw a subset of the available errors.

Using the Promise syntax

The try/catch syntax is the modern way to catch errors, and it's the approach that's used throughout the documentation, but it's not a strict requirement. You can also use the Promise syntax:

import { addElementAtPoint } from "@canva/design";
import { CanvaError } from "@canva/error";

addElementAtPoint({
  type: "embed",
  url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
}).catch((error) => {
  if (error instanceof CanvaError) {
    console.log("CanvaError:", error.code);
  }

  console.log(error);
});

Handling other errors

Be mindful of the fact that other errors may occur throughout the lifecycle of an app, such as errors from native browser APIs or third-party libraries — that is, handling errors from the Developers SDK doesn't mean that all possible errors are handled.

List of error codes

For every code a CanvaError can carry, see Error codes.