Showing results for 
Show  only  | Search instead for 
Did you mean: 
New Member

API Error Responses

Hi All,

I was checking the error response document in Canvas API. Could not find one yet. Do you guys have any reference for that ?

We were trying testing API to trigger error responses. It seems that API Error responses are not very structured. For instance API would return 400 - Bad request HTTP error code for few different reason. We cant actually decide an action based on that response.


4 Replies
Community Coach
Community Coach

Hello  @manoj_lasantha  Welcome to the Canvas Community.  Thank you for posting your question.  I don't really have an answer for you myself, but I wanted to let you know that I am going to share your question with the Canvas Developers‌ group here in the Community in hopes that your question will get some additional exposure.  If you are not yet following this group, please use the link that I have provided, and then click on the "Follow" button at the top right corner of that page.  Also, you may need to click on the "Actions" menu (also at the top right) and then choose "Join group".  I hope this will be of help to you.  Good luck!

0 Kudos
Community Champion

 @manoj_lasantha , 

I am not aware of any public document that has these codes in it. Most of the API documentation is built into the source code rather than in separate documents. When something isn't in the documentation, looking at the source code itself is a good approach to take.

My experience has been that Canvas generally does not provide a lot of error messages with their API calls that go bad. The source code may perform a few checks and then there's a catch-all if it wasn't one of the checked-for situations. A bad request means that something is not what it was expecting to get, but rather than trying to figure out what portion of it was bad, Canvas just reports that it was bad and it's up to the user to figure out what was bad. Basically, their approach is that we've told you what we expect your request to look like and if you can't send the information in that way, then we're not going to mess with you.

That said, once I get past that initial testing and debugging, I have rarely had an incidence where an API call fails for a reason other than network trouble. Sure it's possible, but it's very rare. I do a lot of checking of things on my end before I ever send it to Canvas, rather than relying on Canvas to tell me I messed up and then figuring out what to do. This works because I keep a local cache of some of the information in Canvas so I know what it has and what it doesn't. Otherwise you're forced to make a call to tell what Canvas has and then decide what to do. In some cases, that isn't possible since Canvas only has API calls to create, but none to read that information back.

You will be more successful spending time validating the data that you send and keeping track of it when Canvas won't give it back to you than you will be trying to figure out from the Canvas error messages what exactly something means.

But to help, some of the Canvas API documentation does list return codes. For example, in the redirect to the assignment override, the documentation says "(404 otherwise)" so you know a 404 error means that it doesn't have a redirect -- that is, it was "not found", which is what a 404 error is. That's limiting, though.

More information can be obtained by going to the source code in the /app/controllers folder. Then search for ':status => ' (without the quotes). There are currently 342 occurrences when you don't include subdirectories or 363 occurrences if you do include subdirectories.

I have a local copy of the source code, so I changed to the <canvas>/app/controllers folder and did

find * -type f -exec grep -H ':status => ' {} \;

That returns the name of the file and the line of text. You'll see a whole bunch of things like this:

users_controller.rb:      return redirect_to(dashboard_url, :status => :moved_permanently)
users_controller.rb:      return render(:json => { :ignored => false }, :status => 400)
users_controller.rb:      render :json => {:errors => true}, :status => :bad_request
users_controller.rb:          'Invalid date or invalid datetime for birthdate')}}, :status => 400)
users_controller.rb:          format.json { render :json => @user.errors, :status => :bad_request }
users_controller.rb:      render :status => 404, :plain => t('could_not_find_url', "Could not find download URL")
users_controller.rb:        format.json { render :json => {}, :status => 403 }
users_controller.rb:                                                            'Invalid date or invalid datetime for birthdate')}}, :status => 400)
users_controller.rb:      render :json => errors, :status => :bad_request
wiki_pages_api_controller.rb:        render :json => @page.errors, :status => update_params.is_a?(Symbol) ? update_params : :bad_request
wiki_pages_api_controller.rb:        render :json => @page.errors, :status => update_params.is_a?(Symbol) ? update_params : :bad_request
wiki_pages_api_controller.rb:        render :json => @page.errors, :status => :bad_request
wiki_pages_api_controller.rb:        render :json => @page.errors, :status => :bad_request
wiki_pages_api_controller.rb:        render :status => :not_found, :json => { :message => 'No front page has been set' }
wiki_pages_api_controller.rb:        render :status => :not_found, :json => { :message => 'page not found' }

Not all of the information returned is an error code though. But you can see that there is often a message that accompanies the HTTP status code. That information is probably not specific enough to identify the exact problem without you looking at the request that you made.

What you really need to do to make sense out of that is to go into the file and look for the function you're interested in. The exact location can be found from the API documentation where it lists the call that you want to make. For example, here is the List the activity stream endpoint of the Users API.


Over on the right side, you see UsersController#activity_stream

That lets you know that you should look in the "users_controller.rb" file for the "activity_stream" function. Function definitions begin with "def ", so look for "def activity_stream".

That's a short function, so here it is:

  def activity_stream
    if @current_user
      # this endpoint has undocumented params (context_code, submission_user_id and asset_type) to
      # support submission comments in the conversations inbox.
      # please replace this with a more reasonable solution at your earliest convenience
      opts = {paginate_url: :api_v1_user_activity_stream_url}
      opts[:asset_type] = params[:asset_type] if params.has_key?(:asset_type)
      opts[:context] = Context.find_by_asset_string(params[:context_code]) if params[:context_code]
      opts[:submission_user_id] = params[:submission_user_id] if params.has_key?(:submission_user_id)

Down at the bottom, there's a call to render_unauthorized_action, which occurs if you're not the current user. You would have to hunt that down where that occurs. It's in the /app/controllers hierarchy 133 times, but only one of those begins with 'def ' and that's the application_controller.rb file. That file also has some of the more common error messages in it for API errors. Look for "def api_error_json". But there's also a rescue_action_in_api that handles exceptions. That doesn't have any special codes, you would have to look at what caused the exception.

Because the information is so scattered, I would focus on validating your data before you send it and then looking for the error messages in the source code for the functions that you're calling. There may be someone out there who has put all this together in a document and hopefully they'll step up and share, but it's a huge task with source code that changes every three weeks and most people don't have that kind of time to put into maintaining the document.

Community Champion

This doesn't answer your question, but I thought I'd post it here anyway as it can help with error trapping.

In many cases, errors for the same http status code can be distinguished or further understood by looking at the returned json.  There is often an errors array with a message that can tie down the error.

Community Coach
Community Coach

 @manoj_lasantha ,

Were you able to find an answer to your question? I am going to go ahead and mark this question as answered because there hasn't been any more activity in a while so I assume that you have the information that you need. If you still have a question about this or if you have information that you would like to share with the community, by all means, please do come back and leave a comment.  Also, if this question has been answered by one of the previous replies, please feel free to mark that answer as correct.