Status Codes0%
Status Codes
Beginner12 min read•Updated: Jul 11, 2026
HTTP Status Codes and API Contract Standards
HTTP status codes are the standardized vocabulary through which REST APIs communicate the outcome of client requests. Returning accurate status codes—rather than masking errors with generic 200 OK or unhelpful 500 Server Error responses—is essential for API contracts and client error handling.
1. Status Code Classification
HTTP status codes are categorized into five distinct ranges:
Output
1xx (Informational) ──► Request received, continuing process (e.g. 101 Switching Protocols)
2xx (Success) ──► Action was successfully received, understood, and accepted
3xx (Redirection) ──► Further action needed to complete request (e.g. 301 Moved Permanently)
4xx (Client Error) ──► Request contains bad syntax or cannot be fulfilled due to client fault
5xx (Server Error) ──► Server failed to fulfill an apparently valid request due to backend fault
2. Essential Status Codes for Enterprise APIs
| Code | Name | Meaning | Standard Scenario |
|---|---|---|---|
200 | OK | Request succeeded. | Standard GET, PATCH, or PUT response. |
201 | Created | Resource created. | Successful POST request; returns new resource. |
204 | No Content | Succeeded, no body. | Successful DELETE request. |
400 | Bad Request | Malformed syntax / validation failed. | Serializer validation failed (missing required field). |
401 | Unauthorized | Unauthenticated. | Missing or invalid token (Bearer token invalid). |
403 | Forbidden | Authenticated but unauthorized. | User logged in, but lacks permission to view resource. |
404 | Not Found | Resource does not exist. | Object with specified ID or slug not in database. |
405 | Method Not Allowed | Verb not supported. | Sending DELETE to read-only resource. |
409 | Conflict | State conflict. | Duplicate entry violating unique constraint. |
429 | Too Many Requests | Rate limit exceeded. | API throttling threshold breached. |
500 | Internal Server Error | Unhandled backend crash. | Uncaught Python exception in view code. |
502 | Bad Gateway | Upstream failure. | Nginx cannot connect to Gunicorn socket. |
503 | Service Unavailable | Temporary outage. | Maintenance mode or overloaded cluster. |
3. The 401 Unauthorized vs 403 Forbidden Rule
401 Unauthorized: Really means Unauthenticated. The client has not provided valid credentials. HeaderWWW-Authenticateis often included.403 Forbidden: The server knows who the client is, but the authenticated user lacks permission to execute the action. Sending credentials again will not change the outcome.
4. Standardized Error Response Payload Contract
In enterprise REST architectures, never return plain text strings or ad-hoc error shapes. Standardize on RFC 7807 (Problem Details for HTTP APIs):
JSON
{
"type": "https://api.enterprise.com/errors/validation-error",
"title": "Invalid Request Payload",
"status": 400,
"detail": "The payload failed validation checks.",
"errors": {
"email": ["Enter a valid corporate email address."],
"budget": ["Budget must be a positive integer."]
},
"instance": "/api/v1/projects/"
}
5. Using Status Codes in Django REST Framework
DRF provides named constants in rest_framework.status:
Python
from rest_framework import status
from rest_framework.response import Response
def delete_user(self, request, pk):
return Response(status=status.HTTP_204_NO_CONTENT)
def validate_input(self, errors):
return Response(errors, status=status.HTTP_400_BAD_REQUEST)
Interactive Quiz
Practice Quiz
Question 1
What is the critical distinction between HTTP 401 Unauthorized and HTTP 403 Forbidden?
Question 2
What status code should an API return when a client attempts to create an account with an email that is already registered?
Question 3
Why is returning 200 OK with a body like {"error": "Invalid password"} considered an API design anti-pattern?
Question 4
What status code is returned when a client makes more API requests than permitted by the rate limiter?
Question 5
In Django REST Framework, where are standard named status code constants imported from?
Next Lesson
Installing DRF
Continue learning with hands-on practice, examples, and exercises in the upcoming topic.
Related Lessons
| Previous Lesson | Next Lesson |
|---|---|
| HTTP Methods Overview | Installing DRF |
Practice Quiz
Test your understanding of this lesson with 5 questions. Each question has one correct answer.