While trying to open many pages or content online, I’m sure all of us have stumbled across certain errors containing a collection of numbers. Those numbers are actually codes, or more precisely, HTTP status codes - indicators representing a type of HTTP error the user faces.
As developers, the question of which HTTP status code to return for which endpoint, in which situation, is a troublesome task for many. This blog serves to aid the purpose of choosing the right HTTP response for certain endpoint types (including error status codes). Since most HTTP status codes are standardized, here we’ll explain how to adjust to them and use them more efficiently. But before delving into the types of HTTP codes themselves, it’s worth giving a bit of a deeper explanation of what an HTTP status code looks like.
Whenever a client requests anything from a server, the server responds to the request by sending a status code. The first digit of the status code specifies the response class, whilst the remaining two digits serve no classification or categorization function. Five classes are being used to categorize responses:
-
1xx informational response - the request was received and the procedure is continuing
-
2xx successful - the request was received, understood, and accepted
-
3xx redirection - more steps are required to complete the request
-
4xx client error - the request cannot be processed or has incorrect syntax
-
5xx server error - the server failed to fulfill a seemingly legitimate request due to an error
This blog will provide knowledge of the most prevalent HTTP status codes which are required to build APIs successfully. Each code classification will be presented in its separate section for better readability.
2xx Success
This series of status codes indicates that the request has been successful and the browser has successfully received the requested information. Generally, this is the request you would usually want to see for any kind of debugging work.
Hence this set of codes indicates success; it is your responsibility, as a developer, to ensure all of your pages and resources are returning a 2xx status code.
200 OK
-
the expected response to look out for
-
a request was received, understood, and is being processed
-
example: a GET REST API request returns 200 if the desired information has been found
201 Created
-
a new resource has been made as a consequence of the request being accepted
-
example: the response to a POST request will include an object that describes or contains the action's outcome
204 No Content
-
although the request has been successful, the client is not obliged to leave the current page
-
example: you may want to return the 204 (No Content) status code in UPDATE operations where the request payload is large enough not to transport back and forth
3xx Redirection
These kinds of status codes indicate that extra steps are needed from the client to complete the request. During URL redirection, several of these status codes are being applied.
302 Found
-
occurs when a resource of a page you’re trying to access has been temporarily moved to a new location
-
typically, the web server is here to blame hence the redirect occurs automatically, and it has no effect on the user experience
4xx client errors
This series of codes is intended to indicate the client’s fault in making and sending the request to the server.
400 Bad Request
The client’s request cannot (or will not) be processed by the server due to:
-
malformed request syntax
-
deceptive request routing information
-
an exceedingly large file is being uploaded
401 Unauthorised
The client must be authenticated to get the expected response from the server. Re-authenticating may grant access to the desired content.
403 Forbidden
Although the server has recognized the request’s validity and has processed the request itself, access to the content is forbidden due to:
-
illegal actions
-
not having the required permissions to view the content
-
not having the required account type
Unlike to the 401 status code, re-authenticating won’t yield access to the content. The content access is strictly tied to the application’s logic.
404 Not Found
The server cannot yield access to the content due to the content not being found.
Note: Use status code 410 if the content has been permanently deleted.
413 Request entity too large
It signifies that the request has been too large for the server to handle, either because of the request entity is larger than the server’s limits or due to physical limitations.
422 Unprocessable Entity
Although the request’s entity syntax is accurate, and its content type has been received by the server, the server has been unable the process the contained instructions.
Warning: The client should not try re-requesting the content without request modification.
5xx server errors
This series of codes indicate issues with server responses not being shown whilst having a valid and verified request body for a given request. You should check your server immediately if your website is suffering 5xx server failures.
500 Internal Server Error
Displayed when an unexpected circumstance occurs and a more detailed message is unavailable. The server has been put in a situation from which it does not know how to recover. This error type or response is a generic "catch-all" response. Usually, this indicates the server cannot find a better 5xx error code to respond.
502 Bad Gateway
Indicates that the server, while acting as a gateway or proxy, received an invalid response from the upstream server. Usually, this type of error is not due to the client’s end and is an indicator the server is at fault.
504 Gateway Timeout
Indicates that the server, whilst serving as a gateway or proxy, could not get the answer it required from the upstream server to complete the request.
How do we, in Devōt, handle HTTP status codes?
To give you a brief introduction about handling each status code, we’ll present you with a medical application example in which we’ll list out different HTTP states of the application. This way, we hope to provide you with better context as to which status code to pick in what situation.
The patient table fields are as follows: id, uuid (unique), name. None of the attributes are allowed to be null/nil.
-
Doctor wants to list all his patients
-
Request method: GET /patients
-
Response status code: 200
-
Doctor wants to create a new patient
-
Request method: POST /patients
-
Body: valid uuid and name
-
Response status code: 201
-
Doctor wants to create a new patient
-
Request method: POST /patients
-
Body: valid uuid (name not provided)
-
Response status code: 400
-
Doctor wants to create a new patient
-
Request method: POST /patients
-
Body: uuid (already exists) and valid name
-
Response status code: 422
-
Doctor wants to update a specific patient
-
Request method: PATCH | PUT /patients
-
Body: valid uuid and name
-
Response status code: 200
-
Doctor wants to list patients who are associated with another doctor
-
Request method: GET /doctor/{doctor_id}/patients (where doctor_id is another doctor’s id)
-
Response status code: 401
-
Doctor’s assistant wants to create a new patient but has permission only to get a list of them
-
Request method: POST /patients
-
Body: valid uuid and name
-
Response status code: 403
-
Doctor wants to get a specific patient based on the patient’s uuid
-
Request method: GET /patients/{patient_uuid}
-
Case 1: patient_uuid is valid
-
Response status code: 200
-
Case 2: patient_uuid is invalid
-
Response status code: 400
-
Case 3: patient_uuid is empty
-
Response status code: 404
-
Doctor wants to create a new patient with an uuid which is not the type of uuid, but the developers haven’t covered that use case through validation
-
Request method: POST /patients
-
Body: invalid uuid and valid name
-
Response status code: 500
That should cover a basic CRUD application example and every status code to look out for while creating the application itself. If you still have doubts about which status code to pick in what situation, feel free to contact us and we’ll gladly try to help.
