Response Codes Explained

If you have ever made a REST request or looked in the developer tools section of a browser, you have likely seen the three-digit response code that is returned with an HTTP request.  This week, we'll be talking about the different types of response codes you might receive when doing API testing, and what those codes mean.  

100-level Responses:

A 100-level response indicates that the request should continue.  The most common 100-level type is the simple 100 Continue.  This can be used with large requests; it gives the server the opportunity to stop a large request before too much data is transmitted.  You probably won't see this in your API testing, because the server response will continue and complete behind the scenes and will then return a 200-level response. 

200-level Responses:

A 200-level response indicates that the request was successful.  The most common response is the 200 OK.  This simply means that everything went as expected.  Here are some other common 200-level responses:

201 Created- this indicates that a new resource has been created as the result of the request.  For example, a GET request might create a log entry that shows the date, time, and content of the request.

202 Accepted- this indicates that the request was accepted, but is not complete yet.  An example of where this could be used would be a pending change that needs approval before being added to the database.

204 No Content- this means that the request was processed successfully, and that no data was returned.  This might be used with a PUT request, where the content is changed, but the developer saw no need to return the data with the response.  A 200 OK response can also return no data if the developer chooses, but a 204 response should never return any data.  

300-level Responses:

A 300-level response indicates that a resource has been moved.  The most common of the 300-level responses is 301 Moved Permanently. This response should include the new URI in the header, so that the client will know where to point the request next time.  

400-level Responses:

A 400-level response indicates that there was something wrong with the client's request.  The most common of these is 400 Bad Request, which is usually used when the request is malformed or inaccurate in some way.  Examples of this would be a request where there is required data that is not present, or data that has some sort of validation error.  Other common 400-level responses include:

401 Unauthorized- this is usually returned when the client does not have the appropriate authentication to make the request, such as a JWT or a cookie.  

403 Forbidden- this is returned when the client has the appropriate authentication to make the request, but does not have the permission to view the resource.  For example, a user might be logged into the system and be able to request their own data, but should not be able to request another user's data.

404 Not Found- this is returned when the client is making a request for a specific resource, and the server cannot find it.  An example of this would be if a customer with an ID of 100 was requested, and there was no customer with an ID of 100 in the database. 

409 Conflict- this is returned when the request puts data resources in conflict with each other.  One example of this would be if the client was attempting a POST request to create a resource with an id that was already being used.  

500-level Responses:

A 500-level response means that something has gone wrong on the server side of the request.  The most common is the 500 Internal Server Error response, which can be used for a variety of problems.  An example of this would be a request that was attempting to add a record to a database where the database table is not equipped to handle it, because it has too many characters or is the wrong type. Other common 500-level responses include:

502 Bad Gateway- this can happen when the responding server needs to make a request from another server, and the other server is returning an invalid response.

503 Service Unavailable- this is returned when the responding server is temporarily down for some reason. This response can be more helpful than the generic 500 response, because it indicates that the problem is with availability rather than with the database. 

Now that we understand what response codes mean, let's try them out in our Postman Pet Store Collection!  If you have not yet created the collection, see last week's post for instructions.  Click on the first request in the collection: Add Pet.  Underneath the URL of the request, click on "Tests".  In the right-hand side of the window, there will be a list of code snippets that you can use to create assertions.  Scroll down until you find the snippet called "Status code: Code is 200", and click on it. This will automatically add an assertion in the test field that looks like this:  

pm.test("Status code is 200", function () {

    pm.response.to.have.status(200);

});

The "Status code is 200" section of this code is the name of the test you are running.  The "pm.response.to.have.status(200)" section is the expectation of the assertion.  

Click the Save button on the request, and then click the Send button.  In the bottom section of the page, you should see a Test Results section with a "(1/1)" after the section title.  This indicates that 1 test passed, and 1 test was run.  If you click on the Test Results link, you should see "PASS" and "Status code is 200" in the response section.  You have successfully added an assertion to your request!

Let's see what a failed assertion looks like.  To make the assertion fail, simple change the body of the assertion to:

pm.test("Status code is 202", function () {

    pm.response.to.have.status(202);

});

We have set our assertion to expect a 202 response instead of a 200.  Run the request again, and now you should see "(0/1)" next to the Test Results link.  Click on the link, and in the response section, you should see "FAIL" and "Status code is 202".  This indicates that the test named "Status code is 202" has failed.  

Now change the assertion back to expect a 200 response, and add the assertion to all of the other requests in your collection, except for the request called "Verify Delete Pet".  The "Verify Delete Pet" request is looking for a record that no longer exists, so we will not be expecting a 200 response.  Instead, we should be getting a 404 Not Found response.  Let's add this assertion in the Tests section of the request:

pm.test("Status code is 404", function () {

    pm.response.to.have.status(404);

});

Click the Save button to save this assertion.  

If you run this request before you have run the Delete Pet request, you will see the assertion fail, because the pet with the id of 100 still exists.  But if you first run the Delete Pet request, and then run the Verify Delete Pet request, you will see the Delete Pet assertion pass, because the pet with the id of 100 no longer exists in the database.

Now that we have assertions on all of our requests, let's try running the entire collection!  Hover over the name of the Pet Store collection, and click on the chevron (>) that appears to the right of the name.  Click on the "Run" button, and the Collection Runner will open.  Click on the name of your collection, and then click the "Run Pet Store" button.  You should see your tests run, and pass, very quickly!  Your results window should look like this:

At the top of the window, you'll see that your six tests passed, and that zero tests failed.  You'll see the name of each of the requests you created, and the name of each test that you ran for each request, along with the "PASS" indicator.

Next week we'll add some more interesting assertions to our collection!