HTTP Status Codes Cheat Sheet — Every Code Explained

The server received the request headers and the client should proceed to send the body.

Client: POST /upload HTTP/1.1
        Expect: 100-continue
Server: HTTP/1.1 100 Continue
(client now sends the body)

Used with large uploads — the client checks if the server will accept the request before sending the full body.

The server is switching to a different protocol as requested by the client.

Client: GET /chat HTTP/1.1
        Upgrade: websocket
Server: HTTP/1.1 101 Switching Protocols
Upgrade: websocket

Most commonly seen when upgrading an HTTP connection to WebSocket.

The request succeeded. The most common status code.

GET /api/users/1 → 200
{ "id": 1, "name": "Alice" }

Use for: successful GET requests, successful PUT/PATCH updates that return the updated resource.

A new resource was successfully created.

POST /api/users → 201
Location: /api/users/42
{ "id": 42, "name": "Bob" }

Use for: successful POST requests that create a new resource. Include a Location header pointing to the new resource.

The request succeeded but there's no body to return.

DELETE /api/users/42 → 204
(empty body)

Use for: successful DELETE requests, or PUT/PATCH when you don't need to return the updated resource.

The server is returning only part of the resource (range request).

Client: GET /video.mp4
        Range: bytes=0-1023
Server: HTTP/1.1 206 Partial Content
Content-Range: bytes 0-1023/146515

Used for video streaming, resumable downloads, and large file transfers.

The resource has permanently moved to a new URL.

GET /old-page → 301
Location: /new-page

Browsers and search engines will update their links. Use for permanent URL changes, domain migrations, or HTTP→HTTPS redirects.

The resource is temporarily at a different URL.

GET /promo → 302
Location: /seasonal-sale

The client should continue using the original URL for future requests. Use for temporary redirects like maintenance pages.

The resource hasn't changed since the last request — use your cached version.

Client: GET /api/data
        If-None-Match: "abc123"
Server: 304 Not Modified
(no body — client uses cached version)

Saves bandwidth. Works with ETag and If-None-Match or Last-Modified and If-Modified-Since headers.

Like 302, but guarantees the HTTP method won't change.

POST /api/submit → 307
Location: /api/v2/submit
(client re-sends POST to new URL)

Use when you need to redirect a POST and want the client to POST again (not convert to GET).

Like 301, but guarantees the HTTP method won't change.

POST /api/old → 308
Location: /api/new
(client re-sends POST to new URL)

Use for permanent API endpoint changes where you need to preserve the HTTP method.

The request is malformed or invalid.

POST /api/users
{ "email": "not-an-email" }
→ 400
{ “error”: “Invalid email format” }

Use for: invalid JSON, missing required fields, wrong data types, validation errors that aren’t covered by a more specific code.

Authentication is required and has failed or not been provided.

GET /api/profile
(no Authorization header)
→ 401
{ “error”: “Authentication required” }

The name is misleading — it means “unauthenticated”, not “unauthorized”. The client needs to log in.

The client is authenticated but doesn't have permission.

DELETE /api/admin/users/1
Authorization: Bearer user-token
→ 403
{ “error”: “Admin access required” }

Use when the user is logged in but lacks the required role or permissions. Re-authenticating won’t help.

The requested resource doesn't exist.

GET /api/users/99999 → 404
{ "error": "User not found" }

Use for: missing resources, invalid URLs. Sometimes used instead of 403 to hide the existence of a resource from unauthorized users.

The HTTP method is not supported for this endpoint.

DELETE /api/users → 405
Allow: GET, POST

Include an Allow header listing the supported methods.

The request conflicts with the current state of the resource.

POST /api/users
{ "email": "alice@example.com" }
→ 409
{ “error”: “A user with this email already exists” }

Use for: duplicate entries, version conflicts, trying to delete a resource that has dependencies.

The request is well-formed but semantically invalid.

POST /api/orders
{ "quantity": -5 }
→ 422
{ “errors”: [{ “field”: “quantity”, “message”: “Must be positive” }] }

Use for: business logic validation errors. The JSON is valid (not 400), but the values don’t make sense.

The client has sent too many requests (rate limiting).

→ 429
Retry-After: 60
{ "error": "Rate limit exceeded. Try again in 60 seconds." }

Include a Retry-After header telling the client when to try again.

Something went wrong on the server.

GET /api/users → 500
{ "error": "Internal server error" }

The catch-all server error. Never expose stack traces or internal details to the client in production. Log the details server-side.

The server (acting as a gateway/proxy) received an invalid response from the upstream server.

Client → Nginx → App Server (crashed)
→ 502 Bad Gateway

Common when: your app server crashed, a reverse proxy can't reach the backend, or a Lambda function timed out behind API Gateway.

The server is temporarily unable to handle the request.

→ 503
Retry-After: 300
{ "error": "Service under maintenance" }

Use for: planned maintenance, server overload, or temporary outages. Include Retry-After if you know when it'll be back.

The server (acting as a gateway/proxy) didn't get a response from the upstream server in time.

Client → Load Balancer → App Server (too slow)
→ 504 Gateway Timeout

Common when: a database query takes too long, an external API call times out, or the backend is overloaded.

Decision tree for common API operations:

POST (create):
  Success → 201 Created
  Duplicate → 409 Conflict
  Invalid data → 422 Unprocessable Entity
GET (read):
Found → 200 OK
Not found → 404 Not Found
Cached → 304 Not Modified
PUT/PATCH (update):
Updated (with body) → 200 OK
Updated (no body) → 204 No Content
Not found → 404 Not Found
DELETE:
Deleted → 204 No Content
Not found → 404 Not Found

Use a consistent error response structure across your API.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": [
      { "field": "email", "message": "Must be a valid email" },
      { "field": "age", "message": "Must be at least 18" }
    ]
  }
}

Always include a human-readable message and a machine-readable error code.