HTTP Status Codes Classification and Meanings

🏷️ APIs and HTTP Requests / API Architecture Brief Recap

📚 All-in-One📖 Theory Only💻 Code Only

📝 Context Introduction

When working with APIs, every response from a server includes a three-digit HTTP status code. These codes act as a quick summary of what happened with your request—whether it succeeded, failed, or requires further action. Understanding these codes helps engineers debug issues, build reliable integrations, and communicate effectively with backend services. This guide breaks down the five main categories of HTTP status codes and their most common meanings.

⚙️ The Five Status Code Classes

HTTP status codes are grouped into five classes, each defined by the first digit:

1xx (Informational) – The request was received and processing is continuing.
2xx (Successful) – The request was successfully received, understood, and accepted.
3xx (Redirection) – Further action is needed to complete the request (usually a redirect).
4xx (Client Error) – The request contains bad syntax or cannot be fulfilled by the server.
5xx (Server Error) – The server failed to fulfill a valid request.

📊 Common Status Codes Breakdown

✅ 2xx Success Codes

These are the codes you want to see most often—they mean everything worked as expected.

200 OK – The standard success response. The request was processed and data is returned.
201 Created – A new resource was successfully created (common after POST requests).
202 Accepted – The request was accepted for processing, but the action is not yet complete (used for asynchronous tasks).
204 No Content – The request succeeded, but there is no content to return (common after DELETE requests).

🔀 3xx Redirection Codes

These codes tell the client that the resource they requested is available at a different location.

301 Moved Permanently – The resource has been permanently moved to a new URL. Future requests should use the new URL.
302 Found – The resource is temporarily located at a different URL. Future requests should still use the original URL.
304 Not Modified – The resource has not changed since the last request. The client can use its cached version.

❌ 4xx Client Error Codes

These codes indicate the problem is on the client side—bad request, missing authentication, or trying to access something that doesn't exist.

400 Bad Request – The server could not understand the request due to invalid syntax or malformed data.
401 Unauthorized – Authentication is required and has failed or not been provided.
403 Forbidden – The server understood the request, but the client does not have permission to access the resource.
404 Not Found – The requested resource could not be found on the server.
405 Method Not Allowed – The HTTP method used (e.g., GET, POST) is not supported for this resource.
409 Conflict – The request conflicts with the current state of the server (e.g., trying to create a duplicate resource).
422 Unprocessable Entity – The request was well-formed but contains semantic errors (common with validation failures).
429 Too Many Requests – The client has sent too many requests in a given amount of time (rate limiting).

🛠️ 5xx Server Error Codes

These codes indicate the server encountered an error while processing a valid request.

500 Internal Server Error – A generic error message when the server encounters an unexpected condition.
502 Bad Gateway – The server, acting as a gateway, received an invalid response from an upstream server.
503 Service Unavailable – The server is temporarily unable to handle the request (often due to maintenance or overload).
504 Gateway Timeout – The server, acting as a gateway, did not receive a timely response from an upstream server.

🕵️ How to Interpret Status Codes in Practice

When you receive a response from an API, follow this quick mental checklist:

Check the first digit – Is it 2 (success), 4 (client error), or 5 (server error)?
For 4xx codes – Look at your request payload, headers, or authentication token. The problem is likely on your side.
For 5xx codes – The issue is on the server side. Retry the request after a short delay, or contact the API provider.
For 3xx codes – Follow the redirect or check if you need to update your stored URL.

📋 Quick Reference Table

Status Code	Category	Meaning	Common Scenario
200	Success	OK	Data retrieved successfully
201	Success	Created	New record added
204	Success	No Content	Record deleted
301	Redirection	Moved Permanently	URL changed permanently
400	Client Error	Bad Request	Invalid JSON payload
401	Client Error	Unauthorized	Missing API key
403	Client Error	Forbidden	Insufficient permissions
404	Client Error	Not Found	Wrong endpoint URL
429	Client Error	Too Many Requests	Rate limit exceeded
500	Server Error	Internal Server Error	Server bug or crash
502	Server Error	Bad Gateway	Upstream service down
503	Server Error	Service Unavailable	Server under maintenance

💡 Key Takeaways for Engineers

Always check status codes in your API responses before processing the data. Never assume a request succeeded.
Log status codes during development and debugging to quickly identify where issues occur.
Handle 4xx and 5xx codes gracefully in your code—retry on 5xx, fix the request on 4xx.
Use the first digit as your high-level indicator: 2 = good, 4 = fix your request, 5 = server issue.
Remember that 3xx codes are not errors—they are instructions for the client to look elsewhere.

Understanding HTTP status codes is one of the most practical skills for working with APIs. Once you internalize these categories, you'll be able to diagnose most integration issues within seconds.

HTTP status codes are three-digit numbers returned by servers to tell engineers whether a request succeeded, failed, or needs more action.

🌐 Example 1: Checking a 200 OK status code

This example shows how to check if a server response indicates success.

status_code = 200

if status_code == 200:
    print("Request succeeded — everything is working")
else:
    print("Something went wrong")

📤 Output: Request succeeded — everything is working

🔍 Example 2: Identifying client errors with 400 codes

This example demonstrates how to detect when the client made a bad request.

status_code = 404

if status_code >= 400 and status_code < 500:
    print("Client error — check your request")
else:
    print("No client error detected")

📤 Output: Client error — check your request

⚠️ Example 3: Recognizing server errors with 500 codes

This example shows how to identify when the server itself has a problem.

status_code = 503

if status_code >= 500 and status_code < 600:
    print("Server error — the server cannot handle the request")
else:
    print("No server error detected")

📤 Output: Server error — the server cannot handle the request

🔄 Example 4: Handling redirects with 300 codes

This example demonstrates how to detect when a resource has moved to a new location.

status_code = 301

if status_code >= 300 and status_code < 400:
    print("Redirection — the resource moved to a new URL")
elif status_code == 200:
    print("Success — resource found at this URL")
else:
    print("Other status code received")

📤 Output: Redirection — the resource moved to a new URL

🛠️ Example 5: Classifying any status code into its category

This example shows a practical function that tells engineers which category a status code belongs to.

def classify_status(code):
    if code >= 100 and code < 200:
        return "Informational"
    elif code >= 200 and code < 300:
        return "Success"
    elif code >= 300 and code < 400:
        return "Redirection"
    elif code >= 400 and code < 500:
        return "Client Error"
    elif code >= 500 and code < 600:
        return "Server Error"
    else:
        return "Unknown"

print(classify_status(200))
print(classify_status(404))
print(classify_status(500))
print(classify_status(302))

📤 Output: Success Client Error Server Error Redirection

📊 Status Code Classification Table

Code Range	Category	Meaning for Engineers
100–199	Informational	Request received, continuing process
200–299	Success	Request understood and accepted
300–399	Redirection	Further action needed to complete request
400–499	Client Error	Request contains bad syntax or cannot be fulfilled
500–599	Server Error	Server failed to fulfill a valid request