HTTP Status Codes Reference

Comprehensive reference for http status codes reference covering essential concepts, practical examples, and production best practices.

HTTP status codes are the foundation of communication between clients and servers in web applications. When a request fails, a service doesn’t respond, or a client needs to adapt behavior based on server feedback, HTTP status codes provide the definitive answer. This reference compiles the complete set of status codes, their precise meanings, and the real-world nuances that distinguish correct implementation from just “good enough.”

Response Categories and Their Use Cases

1xx: Informational Responses

Use when: the server is processing a request and needs to inform the client of intermediate steps, often before sending the final response.

Common usage:

POST /upload HTTP/1.1
Host: api.example.com
Expect: 100-continue
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="large.zip"
Content-Type: application/zip

[Binary data...]
------WebKitFormBoundary7MA4YWxkTrZu0gW--

The client sends the Expect: 100-continue header, and the server responds HTTP/1.1 100 Continue before receiving the full request body.

Sharp edges:

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRjOGO7BYoN8p9u52SjC366K

2xx: Success Responses

Use when: the request was successfully received, understood, and processed.

Common patterns:

201 Created – Resource Creation

POST /users HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "name": "Alice",
  "email": "[email protected]"
}
HTTP/1.1 201 Created
Location: /users/123
Content-Type: application/json
Content-Length: 125

{
  "id": 123,
  "name": "Alice",
  "email": "[email protected]",
  "created_at": "2023-10-05T12:00:00Z"
}

Key points:

202 Accepted – Asynchronous Processing

POST /jobs HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "type": "report",
  "params": { "start": "2023-01-01", "end": "2023-12-31" }
}
HTTP/1.1 202 Accepted
Content-Type: application/json
Content-Length: 102

{
  "job_id": "job-98765",
  "status": "queued",
  "message": "Job received and queued for processing."
}

Sharp edges:

206 Partial Content – Range Requests

GET /video.mp4 HTTP/1.1
Host: media.example.com
Range: bytes=100000-199999
HTTP/1.1 206 Partial Content
Content-Range: bytes 100000-199999/500000
Content-Length: 100000
Content-Type: video/mp4

[100,000 bytes of video data]

Key points:

3xx: Redirection Responses

Use when: the client needs to follow a new location to complete the request.

Critical distinctions:

301 vs. 302

GET /old-page.html HTTP/1.1
Host: example.com
HTTP/1.1 301 Moved Permanently
Location: /new-page.html
Cache-Control: public, max-age=3600
HTTP/1.1 302 Found
Location: /new-page.html

Sharp edges:

POST /users HTTP/1.1
Host: api.example.com
Content-Type: application/json

{ "name": "Bob" }
HTTP/1.1 303 See Other
Location: /users/456
Content-Type: text/html

<h1>User created: Bob</h1>
POST /upload HTTP/1.1
Host: example.com
Content-Length: 1024

[Binary data...]
HTTP/1.1 308 Permanent Redirect
Location: https://files.example.com/upload

The client resends the POST request to https://files.example.com/upload with the same body and headers.

Key points:

GET /blog/post/123 HTTP/1.1
Host: blog.example.com
If-Modified-Since: Wed, 04 Oct 2023 12:00:00 GMT
HTTP/1.1 304 Not Modified
ETag: "abc123"
Last-Modified: Wed, 04 Oct 2023 12:00:00 GMT

The client uses the cached response and does not receive the body.

4xx: Client Errors

Use when: the client made a malformed request or provided invalid data.

Critical patterns:

400 Bad Request – General Client Error

POST /users HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "name": "",
  "email": "invalid-email"
}
HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 123

{
  "error": "Validation failed",
  "details": [
    {
      "field": "name",
      "message": "Name is required"
    },
    {
      "field": "email",
      "message": "Email is invalid"
    }
  ]
}

Sharp edges:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "errors": [
    {
      "field": "dob",
      "code": "invalid_date",
      "message": "Date must be in YYYY-MM-DD format"
    },
    {
      "field": "skills",
      "code": "min_length",
      "message": "At least 2 skills required"
    }
  ]
}

401 Unauthorized – Authentication

GET /api/profile HTTP/1.1
Host: api.example.com
Authorization: Bearer abc123xyz
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api.example.com", error="invalid_token", error_description="The access token is expired"
Content-Type: application/json

{
  "error": "invalid_token",
  "error_description": "The access token is expired",
  "expires_in": 3600
}

Key points:

WWW-Authenticate: Basic realm="API"

404 Not Found – Resource Missing

GET /users/9999 HTTP/1.1
Host: api.example.com
HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": "User not found",
  "id": 9999,
  "message": "No user with ID 9999 exists."
}

Sharp edges:

HTTP/1.1 410 Gone
Content-Type: application/json

{
  "error": "Resource permanently removed",
  "message": "User 9999 was deleted and will not be restored."
}

5xx: Server Errors

Use when: the server encountered an error while processing the request.

Common patterns:

500 Internal Server Error

POST /orders HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "items": [ { "id": 1, "quantity": 5 } ]
}
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
Content-Length: 187

{
  "error": "Internal server error",
  "details": {
    "timestamp": "2023-10-05T12:05:30Z",
    "trace_id": "a1b2c3d4",
    "error_code": "DB-100",
    "message": "Failed to save order to database"
  },
  "debug": {
    "sql": "INSERT INTO orders ...",
    "params": [1, 5],
    "error": "SQLSTATE[HY000]: General error: 1213 Deadlock found when trying to get lock"
  }
}

Key points:

HTTP/1.1 502 Bad Gateway
Content-Type: text/html

<h1>502 Bad Gateway</h1>
<p>The upstream server failed to respond.</p>

503 Service Unavailable – Maintenance or Overload

HTTP/1.1 503 Service Unavailable
Retry-After: 60
Content-Type: application/json

{
  "error": "Service maintenance",
  "scheduled_end": "2023-10-06T05:00:00Z",
  "message": "Database is being upgraded. Please try again in 1 minute."
}

Sharp edges:

Summary Table of Key Status Codes

CodeMeaningUse Case
200OKStandard success
201CreatedResource created
202AcceptedAsynchronous processing
204No ContentSuccess, no body
206Partial ContentRange requests
301Moved PermanentlyPermanent redirect
302FoundTemporary redirect
303See OtherAfter POST
304Not ModifiedCached response
400Bad RequestGeneral client error
401UnauthorizedAuthentication required
403ForbiddenAccess denied
404Not FoundResource missing
409ConflictState conflict
410GoneResource permanently removed
422Unprocessable EntityValidation errors
500Internal Server ErrorGeneral server error
502Bad GatewayBackend failure
503Service UnavailableServer overloaded
504Gateway TimeoutBackend took too long

This reference is for engineers who need to implement, debug, and optimize HTTP interactions—precisely, not approximately.

This page was rewritten on 10 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.