HTTP Status Codes: The Complete Reference

Status codes are the API's way of talking to you. A professional developer reads a status code and immediately knows what happened, what went wrong, and how to fix it. This lesson is your complete reference for every status code you will encounter.

---

1. Success Codes (2xx) — Deep Dive

200 OK

The most common status code. The request succeeded and the response body contains the result.

When you see it: GET, PUT, PATCH requests that succeed.

curl -s -o /dev/null -w "%{http_code}" https://jsonplaceholder.typicode.com/posts/1
# Output: 200

201 Created

A new resource was successfully created.

When you see it: Successful POST requests.

curl -s -o /dev/null -w "%{http_code}" -X POST \
  https://jsonplaceholder.typicode.com/posts \
  -H "Content-Type: application/json" \
  -d '{"title":"New","body":"Post","userId":1}'
# Output: 201

The response should include:

• The created resource with its new ID
• A Location header pointing to the new resource

204 No Content

The request succeeded but there is nothing to return.

When you see it: Successful DELETE requests, or updates that return no body.

# After deleting a resource
# Response: 204 with empty body

202 Accepted

The request was accepted but will be processed later.

When you see it: Async operations like report generation, bulk email sending.

{
  "status": "accepted",
  "message": "Your report is being generated",
  "jobId": "job-789",
  "statusUrl": "/jobs/job-789/status"
}

You can poll statusUrl to check when the job is complete.

---

2. Redirection Codes (3xx) — What They Mean

301 Moved Permanently

The resource has permanently moved to a new URL.

HTTP/1.1 301 Moved Permanently
Location: https://api.example.com/v2/users

cURL follows redirects with -L:

curl -L http://api.example.com/old-endpoint

302 Found (Temporary Redirect)

The resource is temporarily at a different URL.

304 Not Modified

The resource has not changed since your last request. Used with conditional requests (ETag/If-Modified-Since).

# First request — get ETag
curl -I https://api.example.com/data
# ETag: "abc123"

# Second request — check if changed
curl -H 'If-None-Match: "abc123"' https://api.example.com/data
# Response: 304 Not Modified (no body — saves bandwidth)

---

3. Client Error Codes (4xx) — Complete Guide

400 Bad Request

Your request data is malformed or missing.

Common causes and fixes:

Cause	Example	Fix
Invalid JSON	{"name": "John"	Close the brace: {"name": "John"}
Missing field	No email in body	Add required fields
Wrong type	"age": "thirty"	Use correct type: "age": 30
Extra comma	{"a":1, "b":2,}	Remove trailing comma

401 Unauthorized

You are not authenticated — the server does not know who you are.

Debugging checklist:

1. Is the Authorization header present?
2. Is the format correct? (Bearer TOKEN not just TOKEN)
3. Is the token expired?
4. Is the header name correct? (Some APIs use X-API-Key)

403 Forbidden

You are authenticated but not authorized for this action.

Key difference from 401:

• 401: "Who are you?" (no credentials)
• 403: "I know who you are, but you cannot do this" (insufficient permissions)

404 Not Found

The resource does not exist.

Debugging checklist:

1. Check for typos in the URL
2. Verify the resource ID exists
3. Check the API version (/v1/ vs /v2/)
4. Look for trailing slashes (/users/1 vs /users/1/)

405 Method Not Allowed

You used the wrong HTTP method.

# Trying to DELETE on a read-only endpoint
curl -X DELETE https://api.example.com/public/stats
# Response: 405 Method Not Allowed
# Allowed: GET, HEAD

409 Conflict

Your request conflicts with the current state.

{
  "error": "Conflict",
  "message": "A user with this email already exists"
}

422 Unprocessable Entity

The JSON is valid, but the values are wrong.

{
  "error": "Validation Error",
  "details": [
    {"field": "email", "message": "not-valid is not a valid email"},
    {"field": "age", "message": "must be between 0 and 150"}
  ]
}

Difference from 400:

• 400: JSON syntax is broken
• 422: JSON is valid but field values are wrong

429 Too Many Requests

You hit the rate limit.

{
  "error": "Rate limit exceeded",
  "retryAfter": 30
}

What to do:

1. Check Retry-After header
2. Wait the specified time
3. Implement exponential backoff in your code

---

4. Server Error Codes (5xx) — How to Handle

500 Internal Server Error

The server crashed while processing your request.

What to do:

1. Try again after a minute
2. Simplify your request (fewer fields, smaller payload)
3. Check the API's status page
4. Report with your request details and any X-Request-Id

502 Bad Gateway

The server received an invalid response from an upstream server.

503 Service Unavailable

The server is overloaded or under maintenance.

HTTP/1.1 503 Service Unavailable
Retry-After: 300

504 Gateway Timeout

An upstream server took too long to respond.

---

5. Quick Reference Card

2xx = Success (your request worked)
  200 = OK (read/update succeeded)
  201 = Created (POST succeeded)
  204 = No Content (DELETE succeeded)

3xx = Redirect (resource moved)
  301 = Permanent redirect
  304 = Not modified (use cache)

4xx = Client Error (YOUR problem)
  400 = Bad request data
  401 = Not authenticated
  403 = Not authorized
  404 = Not found
  422 = Validation failed
  429 = Rate limited

5xx = Server Error (THEIR problem)
  500 = Server crashed
  502 = Bad gateway
  503 = Service down
  504 = Gateway timeout

---

Summary and Key Takeaways

1. 2xx means success — check the specific code for details.
2. 4xx means you made a mistake — the error response tells you how to fix it.
3. 5xx means the server has a problem — wait and retry.
4. 401 vs 403: 401 = who are you?, 403 = you lack permission.
5. 400 vs 422: 400 = broken format, 422 = wrong values.
6. Always read the error response body — it usually tells you exactly what is wrong.

---

Lesson Review Quiz