Status Codes

So far every response has been 200 OK. This section covers what the client gets when something goes wrong. Every status code is a three-digit number. The first digit says what kind of outcome it is. A code that starts with 2 means the request succeeded. A code that starts with 4 means there is something wrong with the request. A code that starts with 5 means there is something wrong with the server.

Success

A request for one course that exists, or for a list, gets 200 OK and the representation.

A search that matches nothing also gets 200 OK. Here is the response to /courses?search=astrology:

HTTP/1.1 200 OK
Content-Type: application/json

[]

The request was fine. The search ran and found nothing, so the response is an empty list. A client that searches and gets nothing back should show the user “no courses found” and not an error.

Client errors

A request for one course that does not exist gets 404 Not Found. Here is the response to /courses/EN.601.999:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": "No course with number EN.601.999."
}

Compare this with the empty search. The client asked for one specific course by its identifier, and there is no such course. There is nothing to send back, and the status code says so.

A request with a query parameter value the API does not accept gets 400 Bad Request. Here is the response to /offerings?term=fall-2036:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "Unknown term code fall-2036. Request /terms for the list of codes."
}

This could have been an empty list. There are no offerings in a term that does not exist, so 200 OK with [] would be true. I chose 400 because the terms endpoint defines which codes the API accepts, and a code that is not on that list is a mistake in the request. An empty list would hide the mistake. The client would think the term has no offerings, when the truth is that it sent the wrong code. The same goes for a subject_area value that is not on the subject areas list, and for a parameter the endpoint does not have at all.

Every error response has the same body: a JSON object with one field, error, holding a sentence a developer can read. The status code is what the program acts on. A client decides what to do by the status code, not by matching the text of the message, because the message can change and the code cannot.

Server errors

If the registrar’s system is down, or the API hits a bug, the client gets 500 Internal Server Error. The client did nothing wrong, and sending the same request again may work. A client should treat a 500 as a reason to try again later and not as a reason to change its request.

Here is the full list for this API.

You may have noticed there is no code that starts with 3. Most codes that start with 3 are redirects. A redirect tells the client the resource is at a different URL, and this API does not redirect. There is one code that starts with 3 that is not a redirect, and we will use it shortly.