An Introduction To API Return Codes

An overview of the different HTTP return codes and what they mean

Photo by Andy Kelly on Unsplash

Introduction

REST APIs are designed to work on top of HTTP/HTTPS protocol. For each request sent from the client, a corresponding HTTP response is sent by the server. HTTP Response sent back from the server is expected to contain the following information:

• Status Line — contains protocol version and status code
• Response Headers — contains extra information that could not be fit into the status line. The end of response headers is demarcated by an empty line
• Optional Message Body — By convention, a successful HTTP request would result in an HTTP response with a message body containing information requested by the client. If there is any error, the message body may contain details of what went wrong.

In this tutorial, we will be focusing on HTTP status codes.

What Are HTTP Status Codes?

HTTP Status codes are three digit numerical values sent as a part of the status line of HTTP response from the server. Status codes give an idea of whether the request to the server has been successful or not. The first digit of the HTTP status code gives an idea of what category of response is received. International Assigned Numbers Authority(IANA) maintains the catalog of HTTP status codes according to the standards mentioned in RFC 7231.

Types Of HTTP Status Codes

In this section, we will learn more about the HTTP Status Codes in detail.

1xx Codes

HTTP Status codes that start with 1 informs the client that the request was received, and it is being processed at the server end. Sometimes the server may take a while to process the request if it involves complex and time consuming computations. In such scenarios, it would be a good idea to inform the client that it should wait a while for the response to reach. However, if the client is HTTP/1.0 based and not compatible with HTTP/1.1, this intermediate response should be avoided.

2xx Codes

HTTP Status codes that start with 2 informs the client that the request was successful. Some of the commonly used status codes from this category are:

• 200 OK — It is a standard status code sent as a part of response for successful HTTP request. Usually, a GET request would have a response with this status code.
• 201 CREATED — It indicates that the HTTP Request was successful, and a new entity or resource was created at the server end.
• 204 NO CONTENT — It indicates that the HTTP request was successful but no content is sent as a part of message body.

3xx Codes

A status code that starts with 3 informs the client that a redirection of URL is desired. Looking at the response code, the user should take additional steps to fetch further information. Some of the commonly used status codes from this category are:

• 301 MOVED PERMANENTLY — It is used in case there is a change in the domain or subdomain being accessed. Once a response with this message is received, the client should use the new URL sent as a part of the Location header.
• 307 TEMPORARY REDIRECT — It informs the client that the same request need to be sent to an additional URL. But any subsequent request can be sent to the old URL
• 308 PERMANENT REDIRECT — It informs the client that all future requests should be repeated with another URL. The difference between 301 and 308 is that the associated HTTP methods would not change in case of latter one.

4xx Codes

This class of status codes inform the client that the request was unsuccessful because of the way it was sent from the client. It is a good practice to include a status message as a part of the response body to inform the client on what went wrong with the current request. Some of the commonly used status codes from this category are:

• 400 BAD REQUEST — It is sent when the client sends a request that doesn’t conform to the expected format at the server end. For example, if the client sent an invalid parameter as a part of the POST request, a response with this status code can be sent.
• 401 UNAUTHORIZED — If the client sent an invalid username/password credentials as a part of the request, this status code will be sent as a part of the response to inform the client about authorization failure.
• 403 FORBIDDEN — If the user credentials sent as a part of the request is that of a user who does not have the right to view the information requested, a response with this status code will be sent from the server end.
• 404 NOT FOUND — If the resource requested does not exist, then this response code will be used by the server to inform the client about it.
• 405 METHOD NOT ALLOWED — This is sent if the requested method is not supported for the URL.
• 409 CONFLICT — It is sent as a response if the request cannot be processed due to some conflict at the server end such as simultaneous edit requests for same resource from multiple sources.

5xx Codes

If a response code starts with 5, then it informs that the request was unsuccessful due to an error at the server end. Some of the commonly used status codes from this category are:

• 500 INTERNAL SERVER ERROR — Standard and generic error code sent for a server error.
• 502 BAD GATEWAY — Indicates that the server, while acting as a gateway or proxy, received an invalid response from the upstream server.
• 503 SERVICE UNAVAILABLE — If the server is too busy processing other requests, this status code is returned. It should be temporary and subsequent retries may result in a successful response once the server load is reduced.

Using Proper HTTP Status Codes In A REST API

GET Request

• A successful GET Request shall return 200 OK as a part of the HTTP Response.
• If the request resource does not exist, 404 NOT FOUND shall be returned.
• If only authorized users can view the data and the credentials sent as part of the request are erroneous, a 401 UNAUTHORIZED status code shall be sent.
• If the user does not have the rights to view the data, a 403 FORBIDDEN status code shall be sent.

POST Request

A successful POST request would create a new resource at the server end. So, 201 CREATED shall be sent as the status code in the response body. The location to new resource shall be sent as a part of the Location header in the HTTP Response. If the POST request was unsuccessful, sending an appropriate response code would let the client know what went wrong.

• If POST method is not implemented at the server end, 405 METHOD NOT ALLOWED shall be used to inform the client about it.
• If the client sent wrong data as a part of the POST request, 400 BAD REQUEST should be used.
• If the client used invalid credentials, it should use 401 UNAUTHORIZED status code.
• If the client used credentials of a user who does not have the right to create a new resource, 403 FORBIDDEN shall be used.

PUT Request

A successful PUT request would modify an existing resource and send 204 NO CONTENT as the status code. If the resource is not available, it shall create a new resource and send 201 CREATED as status code in response body.

If the PUT method is not implemented, 405 METHOD NOT ALLOWED shall be used.

• If the client sent invalid data, 400 BAD REQUEST should be used.
• If the client used invalid credentials, it should use 401 UNAUTHORIZED status code.
• If the client used credentials of a user who does not have the right to modify the resource, 403 FORBIDDEN shall be used.

DELETE Request

A Successful DELETE request will remove an existing resource and send 204 NO CONTENT as status code.

• If the resource does not exist, 404 NOT FOUND shall be sent as the response status code.
• If the DELETE method is not implemented, 405 METHOD NOT ALLOWED shall be used as response code.
• If the client used invalid credentials, it should use 401 UNAUTHORIZED status code.
• If the client used credentials of a user who does not have the right to delete the resource, 403 FORBIDDEN shall be used.

In all the standard methods, if there is any server error, appropriate 5xx status code shall be returned as a part of the response code.

Conclusion

In this tutorial, we learnt about HTTP Status codes and how they should be used in REST APIs. It is important to use the right status code for a given request because that is the standard way for the client would understand what went wrong with the request it sent to the server.