Error codes

When the Oak Curriculum API cannot return a successful response, it will return an HTTP status code and a short message explaining what happened.

Most successful requests return a 200 status code. If you receive an error, the status code will help you decide what to check next. The most common errors are 400, 401, 404 and 429.

Understanding 400 errors

A 400 Bad Request means the API understood your request, but could not return the content in the way requested. It does not mean that the endpoint is broken.

In the Oak Curriculum API, a 400 most often means one of the following:

• The content exists, but cannot be returned for this query because of licensing or copyright restrictions.
• A lesson resource, such as a quiz, transcript or downloadable asset, is not available for the lesson you requested.
• The request asks for content outside the currently available curriculum coverage.

If the response includes data.cause, use that first. It gives the most specific explanation for the 400.

{
  "message": "Lesson not available: \"example-lesson-slug\"",
  "data": {
    "cause": "Content is blocked for copyright reasons"
  }
}

The message tells you which part of the request failed. The data.cause explains why the API could not return it.

Other common errors

401 Unauthorized means your API key is missing or invalid. Check that you are sending your key in the Authorization header in this format:

Authorization: Bearer <API_KEY>

404 Not Found means the endpoint or content could not be found. Check that the URL is correct and that the slug exists in the API data.

429 Too Many Requests means your key has exceeded its rate limit. Wait until the limit resets before trying again. Rate limit information is returned in the response headers when your request is subject to a limit.

If you still need help

• If you think your request should work, please get in touch and include:
• The full endpoint you requested, without your API key.
• The status code you received.
• The response message and data.cause, if present.
• The date and time of the request.

This will help us understand whether the issue is with the request, the content available through the API, or the API itself.