Error responses

When an API request fails, an error response is returned that includes a structured error object. This error object contains:

A code property with a standardized error code that can be used for programmatic error handling.
A message property with a human-readable description of what went wrong.

For example:

{
  "code": "invalid_access_token",
  "message": "Access token is invalid"
}

JSON

Error codes

The following error codes can be returned by the Connect APIs:

internal_error
invalid_field
invalid_header_value
permission_denied
too_many_requests
not_found
bad_request_body
bad_http_method
bad_request_params
bad_query_params
endpoint_not_found
unsupported_version
invalid_access_token
revoked_access_token
missing_field
missing_scope
invalid_grant
invalid_request
invalid_client
unauthorized_client
unsupported_grant_type
invalid_scope
invalid_basic_header
invalid_file_format
quota_exceeded
unsupported_content_type
request_too_large
folder_not_found
item_in_multiple_folders
asset_not_found
max_limit_reached
permission_not_found
permission_exists
unauthorized_user
user_not_found
group_not_found
app_not_found
content_not_found
doctype_not_found
design_not_found
offset_too_large
page_not_found
design_or_comment_not_found
design_or_thread_not_found
design_type_not_found
team_not_found
comment_not_found
too_many_comments
too_many_replies
message_too_long
thread_not_found
reply_not_found
design_not_fillable
autofill_data_invalid
feature_not_available
license_required

Handling errors

Use the error code to handle errors programmatically in your application. The error codes are standardized across all Connect API endpoints, so you can implement consistent error handling logic.

For example:

try {
  const response = await fetch('/v1/designs', {
    headers: {
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
    }
  });

  if (!response.ok) {
    const error = await response.json();

    switch (error.code) {
      case 'invalid_access_token':
        // Handle authentication errors
        redirectToLogin();
        break;
      case 'permission_denied':
        // Handle authorization errors
        showPermissionError();
        break;
      case 'not_found':
        // Handle resource not found
        showNotFoundError();
        break;
      default:
        // Handle other errors
        showGenericError(error.message);
    }
  }
} catch (err) {
  // Handle network errors
  showNetworkError();
}

JAVASCRIPT

Troubleshooting common errors

The following table provides guidance on common error codes you may encounter when using the Connect APIs:

Error Code	What it means	How to troubleshoot
`invalid_access_token`	The provided access token is malformed, expired, or invalid.	Check that your access token is correctly formatted and hasn't expired. Refresh the token if needed, or re-authenticate the user. For more information, see Authentication.
`permission_denied`	The user doesn't have permission to access the specified resource, such as a design.	Handle the error and consider notifying the user that they don't have permission to access the resource.
`missing_scope`	The access token doesn't include a required scope for this endpoint.	Add the missing scope to your OAuth authorization request and have the user re-authorize your integration. For more information, see Authentication
`not_found`	The requested resource doesn't exist or isn't accessible.	Verify the resource ID is correct and the user has access to it. The resource may have been deleted or moved.
`design_not_found`	The specified design doesn't exist or isn't accessible.	Check the design ID is valid and the user has permission to access it. The design may have been deleted or is in a team the user can't access.
`too_many_requests`	You've exceeded the API rate limits.	Implement exponential backoff and retry logic. Review your request patterns and consider caching responses to reduce API calls. For polling asynchronous job endpoints, see API requests and responses.
`bad_request_body`	The request body is malformed or contains invalid data.	Validate your JSON payload against the API schema. Check for missing required fields or incorrect data types.
`bad_request_params`	Invalid parameters in the request URL.	Review the endpoint documentation and ensure all required parameters are provided with correct values.
`invalid_field`	A specific field in your request contains invalid data.	Check the error message for details about which field is invalid and review the expected format or constraints.
`missing_field`	A required field is missing from your request.	Add all required fields as specified in the API documentation for the endpoint you're calling.
`internal_error`	An unexpected error occurred on Canva's servers.	This is usually a temporary issue. Retry your request after a brief delay. If the problem persists, see if there is a known incident on Canva Status⁠(opens in a new tab or window) or contact Canva support.