Why Does an API Return 4xx and 5xx Errors? A Comprehensive Guide to Understanding HTTP Status Codes

Imagine you are at a popular restaurant. You call the waiter and order “Budget Teh Tarik Iced Tea.” A few minutes later, the waiter returns with an update. However, instead of serving your drink, one of two possible scenarios occurs:

1. Scenario A: The waiter says, “Sorry, the Budget Set menu is not listed in our menu” or “Sorry, you have not paid the VIP admission fee required to order this menu.”
2. Scenario B: The waiter returns with a panicked face and says, “Sorry, the kitchen water pipe suddenly burst badly and our stove exploded, so we cannot serve any orders right now.”

In web development and Application Programming Interfaces (APIs), the HTTP Status Code is the “waiter’s answer.” These three-digit codes are a global communication standard between client applications (browsers, mobile applications) and the servers where data is stored.

When a request succeeds, the server sends a success code such as 200 OK. However, when a problem occurs, communication moves into the realm of 4xx or 5xx errors. Understanding the fundamental differences and the detailed meaning of each code is an essential skill for software engineers, testers, and technology product managers.

Quick Summary (Quick Rule of Thumb)

Before examining each code in detail, the simple golden rule for distinguishing HTTP error groups can be summarized as follows:

• Error 4xx (Client-Side Error): “This Is Your Problem (Client)”
  The error occurs because the request sent by the client is invalid, incomplete, unauthorized, or asks for something that does not exist. The server understands the request, but rejects it because the problem is on the sender’s side.
• Error 5xx (Server-Side Error): “This Is Our Problem (Server)”
  The request sent by the client is correct and valid. However, the server experiences an internal failure, crash, overload, or technical infrastructure problem and is therefore unable to process the request.

In-Depth Look at 4xx Errors (Client-Side Errors)

Errors in the 4xx category indicate that the client is responsible for the problem. A frontend application, mobile app, or script calling the API sends a request that violates the rules established by the server.

400 Bad Request

The server cannot understand the request because its syntax is malformed or its data format is incorrect.

• Analogy: You fill out a physical registration form but write the phone number using alphabetic characters. The clerk immediately returns it because the format is invalid.
• Common Causes: Malformed JSON (missing quotation marks or curly braces), an incorrect parameter data type, or a missing required header.

401 Unauthorized vs 403 Forbidden

These two statuses are often confused because both are related to access control, but their concepts are clearly different:

404 Not Found

The requested resource or URL cannot be found on the server.

• Analogy: You are looking for a house at the address “Jalan Mawar No. 999,” but the street only has houses up to number 100.
• Common Causes: A typo in the API endpoint URL, the requested data ID has been deleted from the database, or the backend routing configuration has not been registered.

405 Method Not Allowed

The API endpoint exists and can be found, but the HTTP method being used (GET, POST, PUT, DELETE) is not allowed for that endpoint.

• Analogy: You go to a valid ATM, but try to insert cash into the slot where cash is dispensed (using the wrong method at the right place).
• Common Causes: Sending a POST request to an endpoint that only accepts GET requests.

422 Unprocessable Entity

The request syntax is correct (valid JSON), but the data violates the server’s business logic rules.

• Analogy: You fill out a form correctly, but enter “February 30” as the date of birth. The number format is correct, but the value is logically invalid.
• Common Causes: Data validation failure (for example, a negative age or a password shorter than 8 characters).

429 Too Many Requests

The client has sent too many requests within a certain period (Rate Limiting).

• Analogy: You knock on someone’s door 100 times in one second. The homeowner refuses to open the door until you calm down.
• Common Causes: Repeated automated form submissions, scraping data without pauses, or a brute-force attack.

Practical Checklist for Client Developers (How to Debug 4xx Errors)

• Check the URL structure, path parameters, and query string for typos.
• Check the request body JSON structure using a JSON Validator to make sure there are no syntax errors.
• Check that the Content-Type header is set correctly (for example: application/json).
• Check the availability and expiration of authentication tokens (such as a JWT Bearer Token) in the Authorization header.
• Check that the HTTP method used matches the official API documentation (Swagger/Postman).

In-Depth Look at 5xx Errors (Server-Side Errors)

When a 5xx error appears, the client has done its job correctly. However, a failure occurs in the backend architecture, application server, or database.

500 Internal Server Error

A generic error message indicating that the server encountered an unexpected condition that caused it to fail to process the request.

• Analogy: The chef in the kitchen suddenly faints while preparing your order, so the order cannot be completed.
• Common Causes: An unhandled exception in backend code, a null variable being accessed, or a database connection failure that is not handled with try-catch.

502 Bad Gateway

A server acting as a gateway or proxy receives an invalid response from an upstream server.

• Analogy: The waiter (proxy) goes to the kitchen (upstream) to get the food, but the chef (upstream) gives the waiter an empty plate or speaks a language the waiter does not understand.
• Common Causes: A backend application (such as Node.js, Python, or PHP-FPM) has stopped/crashed, so the web server (Nginx/Apache) receives no response.

503 Service Unavailable

The server is currently unable to handle the request because of scheduled maintenance or an excessively high traffic load (overload).

• Analogy: The restaurant puts up a sign saying “Temporarily Closed for Renovation,” or the restaurant is so crowded that the queue spills outside.
• Common Causes: A sudden traffic spike (for example, a flash sale), the server running out of RAM/CPU, or the server being in the middle of a deployment.

504 Gateway Timeout

A server acting as a gateway does not receive a response from the upstream server in time.

• Analogy: The waiter waits for the chef to prepare the food, but the chef is too slow, the waiter’s waiting time expires, and the waiter returns to the customer’s table without the result.
• Common Causes: A database query that is too heavy and slow (slow query), large-scale data processing performed synchronously, or a third-party service (third-party API) that does not respond.

Practical Checklist for Backend/DevOps (How to Debug 5xx Errors)

• Check the Application Logs (for example, via PM2, Datadog, or CloudWatch) to inspect the error stack trace.
• Check server resource usage (CPU, RAM, Disk I/O) to detect resource exhaustion.
• Check that all related services (Database, Redis Cache, Message Queue) are running normally and can connect.
• Check the Slow Query Log in the database and optimize indexes when timeout problems occur.
• Check that Graceful Degradation is used and set a reasonable Timeout Limit on the Reverse Proxy (Nginx).

Quick Recap Table (Cheatsheet)

Conclusion & Closing Message

HTTP Status Codes are not merely random numbers; they are a universal language designed to speed up problem diagnosis in distributed systems.

In simple terms: If the leading digit is 4, check the application request again (client side). If the leading digit is 5, immediately check your backend server logs (server side).

With a solid understanding of the difference between 4xx and 5xx errors, collaboration among frontend developers, backend developers, and the DevOps team will be much more efficient, structured, and harmonious.