How does an API client know if an API request is successful or not? You might think that the API client checks if the response's content is correct, but the reality is much simpler than that. The API client only checks the value of the HTTP response code. You probably see the Error 404 page not found every now and then when browsing the internet - that 404 is an HTTP response code.
So, what exactly are these codes and why should we care as API Developers?
HTTP Response Codes - Why we need them
Status codes or response status codes are code numbers that are issued by a server or API in response to a client’s request. Easy - you send a request to a server or an API and in response you get a message and a number. The message is, actually, the response we are requesting. It can be, for example, a list of records in response to a GET or it could be a message saying that our record has been successfully (or not successfully) added to our system.
So, why do we need these codes? Basically because we need an automatic way to identify what type of response we are getting. And that’s something an API client cannot figure out only from the content of the message in response. This is something that we can do, because we are able to understand the content and context of the response. But our API client does not have that ability.
As a matter of fact, for API clients the response status code is more important, it’s the only thing they look at.
This is what the HTTP protocol solves with HTTP response codes. With response codes we are classifying the type of responses we get, so that regardless of the content of the response any system making an HTTP request can determine if the response is successful or not, and if not why not.
HTTP Codes Categories
A response code is a 3-digit number, with the first digit indicating the type of response. The HTTP protocol defines 5 categories of response status codes:
- 1xx informational response - This code indicates the request has been received and the server/API is continuing the process
- 2xx successful - These codes indicate that the request has been received, accepted and successful
- 3xx redirection - These codes indicate the request has been redirected and further actions will take place before getting a final response
- 4xx client error - These errors indicate there’s been an error and this error is on the client side (because of bad syntax for example)
- 5xx server error - These errors indicate that the server or API has failed to provide a response
Let’s see some examples and we’ll understand it better. Here’s the list of the most common response status codes, or at least the ones that I, personally, use the most:
2xx Successful Status Codes
Normally, when we see in the response of our API request that we get a 2xx status code we are happy :), because this means that our request was successful and that we got the info we were asking for.
Depending on the operation or method we were using, the meaning of successful request may be different, that’s why we use different 2xx status codes:
[For a full list of all HTTP response codes you can visit this link]
200 - OK
The most common one is 200. Typically is what we get when our browser gets the page we requested or when we get the list of records your API client was requesting to the API/server.
201 - CREATED
We normally get a 201 in response to a POST/PUT request, and this means our request was successful and the server created the resource we requested. We normally use a 201, when our API has successfully created a new record in our system/database for example
202 - ACCEPTED
In some of our applications, especially in asynchronous ones, sometimes we just need to let the requester know that the request has been accepted and that the processing will be completed later. The request might or might not be completed successfully later on but we use this type of response as a way to acknowledge the request
3xx Redirection
When we see a 3xx response status code it just basically means that our request has been redirected. It does not mean our request has been succesful or has failed, it just let us know that the resource we were requesting has probably been moved somewhere else
4xx Client Error
A 4xx error indicates there is an error in the request and the error is located on the client side
Normally, when we see this type of error, it means that there’s something wrong in the request - we might be requesting a resource that does not exist or there might be something wrong in our request (a missing parameter, bad syntax in the body...). There are multiple reasons why a request might be wrong, but having different code errors really helps us. Here are a few:
400 - Bad Request
We get a 400 when there’s something wrong in the syntax of the request. Some examples: invalid or missing parameter, invalid or missing header
401 - Unauthorized
This code means that the server/API requires authentication to access the requested resource and that you’ve probably have not provided a valid identity or none identity
403 - Forbidden
This means that the user or token we’re using in the request does not have the permissions to perform the operation requested in the request. Unlike 401, the server/API knows the identity provided but that identity has not been granted access
404 - Not Found
We get a 404 when the resource we’re requesting does not exist. So, it could be that we’ve got the wrong URL or the wrong name of the resource. Or it could be that the resource does not exist anymore in the system, for example if we are sending a GET to a particular user that does not exist or a GET to a product that is out of stock
405 - Method Not Allowed
This means that the server/API recognizes the resource we’re requesting but the operation or method we’re trying to perform on it (GET, POST, PUT,...) is not allowed
429 - Too Many requests
We normally find this error when the resource we’re requesting is protected to prevent a DoS attack or when there’s some kind of throttling limiting the number of requests (to provide an SLA for example).
5xx Server Error
Lastly, a 5xx error indicates that there’s an error processing the request and the error is located in the server side. Here are some of the most common codes.
500 - Internal Server Error
This error means that something went wrong when the server tried to process the request. In mule we can find this error for example when our API cannot connect to the backend server
502 - Bad Gateway
Normally we get this error when the resource we’re requesting is protected by an API gateway and there’s an issue with that gateway. So, in this case this code helps us to identify that the problem will probably be at the gateway and not at the API itself
503 - Service Unavailable
You don’t want to see this error. This means the server or service you’re trying to connect is down.
Conclusion
As we can see response codes are a great mechanism that the HTTP protocol provides to quickly identify the result of an HTTP request. With just one code we know if our request has been successful or not, and if not where the error is coming from. That’s great info for users/requesters but it’s even greater for a machine as we’ll be able to implement automatic actions based on the codes received. For example we can decide to retry our request if we’re getting a 503 because we know the issue was that the server was not available at that time. That’s what we call an Exception Handling Strategy, but we’ll see it in detail in a future post.
We normally explain the response codes from the point of view of the requester, as a guide to understand and troubleshoot the response. In the next post, we’ll deep dive into mule, as API producers and will see when we need to use these codes in our design and implementation of our mule apps.
Hope that helps!