HTTP Status Codes Overview

HTTP status codes tell clients whether their request succeeded or failed, and why. Using the right status code is essential for good API design.

Status Code Categories

Status codes are grouped into five categories:

Range	Category	Description
1xx	Informational	Request received, continuing process
2xx	Success	Request successfully received and processed
3xx	Redirection	Further action needed to complete request
4xx	Client Error	Request contains bad syntax or cannot be fulfilled
5xx	Server Error	Server failed to fulfill valid request

2xx Success Codes

200 OK

The standard success response. Use for:

• Successful GET requests
• Successful PUT/PATCH updates
• Any successful operation that returns data

GET /api/users/123
HTTP/1.1 200 OK

{ "id": 123, "name": "Alice" }

201 Created

A new resource was created. Use for successful POST requests.

POST /api/users
HTTP/1.1 201 Created
Location: /api/users/124

{ "id": 124, "name": "Bob" }

204 No Content

Success, but no content to return. Use for:

• Successful DELETE requests
• Updates that don't return the updated resource

DELETE /api/users/123
HTTP/1.1 204 No Content

202 Accepted

Request accepted for processing, but not yet complete. Use for asynchronous operations.

POST /api/reports/generate
HTTP/1.1 202 Accepted

{ "jobId": "abc123", "status": "processing" }

4xx Client Error Codes

400 Bad Request

The request was malformed or invalid.

POST /api/users
{ "email": "not-an-email" }

HTTP/1.1 400 Bad Request
{ "error": "Invalid email format" }

401 Unauthorized

Authentication is required or has failed.

GET /api/users
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer

403 Forbidden

Authenticated but not authorized for this resource.

DELETE /api/admin/users/1
HTTP/1.1 403 Forbidden
{ "error": "Admin access required" }

404 Not Found

The requested resource doesn't exist.

GET /api/users/99999
HTTP/1.1 404 Not Found
{ "error": "User not found" }

409 Conflict

Request conflicts with current state (e.g., duplicate email).

POST /api/users
{ "email": "existing@example.com" }

HTTP/1.1 409 Conflict
{ "error": "Email already registered" }

422 Unprocessable Entity

Request was well-formed but had semantic errors.

POST /api/orders
{ "quantity": -5 }

HTTP/1.1 422 Unprocessable Entity
{ "error": "Quantity must be positive" }

429 Too Many Requests

Rate limit exceeded.

GET /api/users
HTTP/1.1 429 Too Many Requests
Retry-After: 60

5xx Server Error Codes

500 Internal Server Error

Generic server error - something unexpected happened.

GET /api/users
HTTP/1.1 500 Internal Server Error
{ "error": "Something went wrong" }

502 Bad Gateway

Server received invalid response from upstream.

503 Service Unavailable

Server temporarily unavailable (maintenance or overload).

GET /api/users
HTTP/1.1 503 Service Unavailable
Retry-After: 300

504 Gateway Timeout

Upstream server didn't respond in time.

Exercise: Match Status Codes to Scenarios

Common Mistakes

Don't Use 200 for Everything

# Bad
POST /api/users
HTTP/1.1 200 OK
{ "error": "Email already exists" }

# Good
POST /api/users
HTTP/1.1 409 Conflict
{ "error": "Email already exists" }

Don't Use 500 for Client Errors

# Bad - client sent invalid data, not server's fault
POST /api/users
HTTP/1.1 500 Internal Server Error

# Good
POST /api/users
HTTP/1.1 400 Bad Request

Use 401 vs 403 Correctly

• 401: "Who are you?" (not authenticated)
• 403: "I know who you are, but you can't do this" (not authorized)

Quick Reference

Code	Name	When to Use
200	OK	General success with response body
201	Created	Resource created successfully
204	No Content	Success with no response body
400	Bad Request	Invalid request syntax
401	Unauthorized	Authentication required/failed
403	Forbidden	Authenticated but not authorized
404	Not Found	Resource doesn't exist
409	Conflict	State conflict (duplicate)
422	Unprocessable	Semantic errors in request
429	Too Many Requests	Rate limited
500	Internal Error	Unexpected server error
503	Unavailable	Server temporarily down

Choosing the right status code makes your API self-documenting and helps clients handle responses appropriately.