Error Handling

Handle errors gracefully to improve reliability


In this section:

Error Handling Patterns

Learning applications integrated with the Knewton API should thoughtfully handle errors to ensure that the student and instructor experience is as smooth as possible. There are various common error-handling patterns that applications can utilize in different situations.

Error handling pattern

For example:

  • Pattern 1: The application exposes some information about the problem to the user and, optionally, asks them to retry their action, e.g. refill an input field and submit again.
  • Pattern 2: The partner application repeats the request behind the scenes. The request should be repeated a limited number of times, with a reasonable constant or exponential backoff between attempts.
  • Pattern 3: The partner application shows alternative content to the user. For example, if retrieval of a Knewton content recommendation fails, the application may fall back to picking content from a target learning objective randomly.
  • Pattern 4: The partner application places requests in a queue for retrying after showing the next screen.

API Status Code Ranges

  • 2xx - Successful call.
  • 4xx - There was an error in your call, likely due to a malformed request. Except in the case of a 429 error (too many requests), a 4xx resp is an indication that there is a bug in the partner application, and the request should not be repeated without modification.
  • 5xx - The request was correctly formed but there is an issue on Knewton’s side, which may be temporary.

API Status Code Reference

Status Code Status Reason Error Handling
200 OK The request completed successfully.  
201 Created The resource was created successfully.  
202 Accepted The request was received and will be processed asynchronously.  
204 No Content The request was successful, and there is no data to return. (e.g. graded or ungraded event was accepted.)  
207 Partially Accepted The request was partially successful, parse the response body to identify successful and failed parts. (e.g. one registration was assigned successfully and another failed.)  
400 Bad Request The request was malformed.  
401 Unauthorized (Unauthenticated) The user is not authenticated. (e.g. There is no token or the token has expired.) Refresh the access token or retrieve a new token, then retry the request. See Implementation guide.
403 Forbidden (Unauthorized) The user is authenticated, but not authorized (does not have permission to do this operation). Utilize pattern 1 or 3. Additionally, application authors should follow up to ensure that Knewton API calls are only made with the token of a user has permission to access/update the relevant resource. See the “Authorization” sections in each API endpoint reference page.
404 Not Found The requested resource does not exist. The URL may be malformed, or an entity identified by a request parameter may not exist, or may be invisible to the user whose token is used to make the call. Utilize pattern 1 or 3. If a race condition between deletion and retrieval of a resource caused the 404, pattern 1 is most appropriate. Additionally, application authors should follow up to ensure that URLs are well-formed and that the partner application’s entity IDs are mapped correctly to Knewton Platform entity IDs when relevant.
405 Method Not Allowed The method used to access the endpoint is incorrect.  
422 Unprocessable Entity Some part of the JSON request was ill-formed and could not be parsed, or it could be parsed but one of the fields is incorrect, perhaps with a wrong UUID or disallowed field. Also returned whenever an entity limit was exceeded. Utilize pattern 1 or 3. See Entity limits for further information
429 Too Many Requests Rate limit exceeded for this endpoint. Utilize pattern 2 if the response data is needed to drive the user experience, falling back to patterns 1 or 3 if retries are not successful. Utilize pattern 4 if the response data is not immediately needed. Note that exponential backoff should be used when retrying after a 429.
500 Internal Server Error Server Error. Utilize a combination of patterns 2 and either 1 or 3.

Troubleshooting

Partner applications should log Knewton API request and response information to assist with troubleshooting. When reaching out to your Knewton representative with questions regarding errors, please include the following information to expedite the investigation:

  • The environment in question.
  • The date and time (with time zone) of the API request.
  • The API request URL.
  • Any relevant IDs (e.g. account ID, registration ID, goal ID, etc.) included as API request parameters.
  • The API response status code
  • The API response body, which should include an error message and an error_id.