Exceptions

CanvasAPI may return a number of different exceptions, which are listed below.

Quick Guide

Exception Status Code Explanation
BadRequest 400 Canvas was unable to process the request.
InvalidAccessToken 401 The supplied API key is invalid.
Unauthorized 401 CanvasAPI’s key is valid, but is unauthorized to access the requested resource.
Forbidden 403 Canvas has denied access to the resource for this user.
RateLimitExceeded 403 Canvas is throttling this request. Try again later.
ResourceDoesNotExist 404 Canvas could not locate the requested resource.
Conflict 409 Canvas had a conflict with an existing resource.
UnprocessableEntity 422 Canvas was unable to process the request.
RequiredFieldMissing N/A A required keyword argument was not included.
CanvasException N/A An unknown error was thrown.

Class Reference

class canvasapi.exceptions.CanvasException(message)

Base class for all errors returned by the Canvas API.

The CanvasException exception is a basic library exception that all other exceptions inherit from. It is also thrown whenever an error occurs but a more specific exception isn’t available or appropriate.

Here’s a simple example of catching a CanvasException:

from canvasapi.exceptions import CanvasException

try:
    canvas.get_course(1)
except CanvasException as e:
    print(e)
class canvasapi.exceptions.BadRequest(message)

Canvas was unable to understand the request. More information may be needed.

The BadRequest exception is thrown when Canvas returns an HTTP 400 error.

class canvasapi.exceptions.InvalidAccessToken(message)

CanvasAPI was unable to make an API connection.

The InvalidAccessToken exception is thrown when Canvas returns an HTTP 401 error and includes a WWW-Authenticate header.

This indicates that the supplied API Key is invalid.

class canvasapi.exceptions.Unauthorized(message)

CanvasAPI’s key is valid, but is unauthorized to access the requested resource.

The Unauthorized exception is thrown when Canvas returns an HTTP 401 error and does NOT include a WWW-Authenticate header.

This indicates that the supplied API Key is probably valid, but the calling user does not have permission to access this resource.

class canvasapi.exceptions.ResourceDoesNotExist(message)

Canvas could not locate the requested resource.

The ResourceDoesNotExist exception is thrown when Canvas returns an HTTP 404 error.

class canvasapi.exceptions.RequiredFieldMissing(message)

A required field is missing.

The RequiredFieldMissing exception is thrown when required fields are not passed to a method’s keyword arguments. This is common in cases where the required field must be represented as a dictionary. See our documentation on keyword arguments for examples of how to use keyword arguments in CanvasAPI.

class canvasapi.exceptions.Forbidden(message)

Canvas has denied access to the resource for this user.

The Forbidden exception is thrown when Canvas returns an HTTP 403 error.

class canvasapi.exceptions.RateLimitExceeded(message)

Canvas has recieved to many requests from this access token and is throttling this request. Try again later.

The RateLimitExceeded exception is thrown when Canvas returns an HTTP 403 error that includes the body “403 Forbidden (Rate Limit Exceeded)”. It will include the value of the X-Rate-Limit-Remaining header (if available) for reference.

class canvasapi.exceptions.Conflict(message)

Canvas had a conflict with an existing resource.

The Conflict exception is thrown when Canvas returns an HTTP 409 error.

class canvasapi.exceptions.UnprocessableEntity(message)

Canvas was unable to process the entity.

The UnprocessableEntity exception is thrown when Canvas returns an HTTP 422 error.