HTTP Status Codes: The Complete Reference Guide for Developers

What Are HTTP Status Codes?

HTTP status codes are three-digit numbers returned by a server in response to a client's request. They tell the client whether the request was successful, redirected, resulted in an error, or requires further action.

Every status code falls into one of five categories based on its first digit:

• 1xx — Informational: Request received, continuing process
• 2xx — Success: Request was successfully received and processed
• 3xx — Redirection: Further action needed to complete the request
• 4xx — Client Error: The request contains bad syntax or cannot be fulfilled
• 5xx — Server Error: The server failed to fulfill a valid request

1xx — Informational Responses

100 Continue

The server has received the request headers and the client should proceed to send the request body. This is used with the Expect: 100-continue header to check if the server will accept the request before sending a large body.

Client: POST /upload HTTP/1.1
        Expect: 100-continue
        Content-Length: 50000000

Server: HTTP/1.1 100 Continue

Client: [sends 50MB file body]

101 Switching Protocols

The server is switching to a different protocol as requested by the client. Most commonly seen when upgrading from HTTP to WebSocket:

Client: GET /chat HTTP/1.1
        Upgrade: websocket
        Connection: Upgrade

Server: HTTP/1.1 101 Switching Protocols
        Upgrade: websocket
        Connection: Upgrade

103 Early Hints

Allows the server to send preliminary headers before the final response. Used to preload resources:

Server: HTTP/1.1 103 Early Hints
        Link: </style.css>; rel=preload; as=style
        Link: </script.js>; rel=preload; as=script

Server: HTTP/1.1 200 OK
        [full response]

2xx — Success

200 OK

The standard success response. The meaning depends on the HTTP method:

• GET — Resource returned in the response body
• POST — Resource created or action performed, result in body
• PUT/PATCH — Resource updated successfully
• DELETE — Resource deleted successfully

201 Created

The request succeeded and a new resource was created. Typically returned after a POST request. The response should include a Location header pointing to the new resource:

HTTP/1.1 201 Created
Location: /api/users/42
Content-Type: application/json

{"id": 42, "name": "Alice", "email": "alice@example.com"}

204 No Content

The request succeeded but there's no content to return. Common for DELETE requests and PUT/PATCH when you don't need to return the updated resource:

DELETE /api/users/42 HTTP/1.1

HTTP/1.1 204 No Content

206 Partial Content

The server is returning only part of the resource, as requested by the client's Range header. Used for resumable downloads and video streaming:

GET /video.mp4 HTTP/1.1
Range: bytes=0-1023

HTTP/1.1 206 Partial Content
Content-Range: bytes 0-1023/146515
Content-Length: 1024

3xx — Redirection

301 Moved Permanently

The resource has permanently moved to a new URL. Search engines will update their index. Use for permanent URL changes:

HTTP/1.1 301 Moved Permanently
Location: https://newdomain.com/page

SEO impact: Passes ~90-99% of link equity to the new URL.

302 Found (Temporary Redirect)

The resource is temporarily at a different URL. The client should continue using the original URL for future requests:

HTTP/1.1 302 Found
Location: https://example.com/temporary-page

304 Not Modified

The resource hasn't changed since the last request. The client should use its cached version. This saves bandwidth:

GET /api/data HTTP/1.1
If-None-Match: "abc123"

HTTP/1.1 304 Not Modified

307 Temporary Redirect

Like 302, but guarantees the HTTP method won't change. If the original request was POST, the redirect will also be POST:

POST /old-endpoint HTTP/1.1

HTTP/1.1 307 Temporary Redirect
Location: /new-endpoint

308 Permanent Redirect

Like 301, but guarantees the HTTP method won't change. The permanent version of 307.

4xx — Client Errors

400 Bad Request

The server cannot process the request due to malformed syntax, invalid parameters, or missing required fields:

{
  "error": "Bad Request",
  "message": "Field 'email' is required",
  "status": 400
}

Common causes:

• Missing required fields
• Invalid JSON syntax
• Wrong data types
• Values out of range

401 Unauthorized

The request requires authentication. The client must provide valid credentials:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api"

Note: Despite the name, 401 means "unauthenticated" (not logged in), not "unauthorized" (no permission).

403 Forbidden

The server understood the request but refuses to authorize it. Unlike 401, authenticating won't help — the user simply doesn't have permission:

{
  "error": "Forbidden",
  "message": "You do not have permission to delete this resource",
  "status": 403
}

401 vs 403:

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

404 Not Found

The server cannot find the requested resource. The most well-known HTTP error:

{
  "error": "Not Found",
  "message": "User with ID 999 not found",
  "status": 404
}

Common causes:

• Typo in the URL
• Resource was deleted
• Incorrect API endpoint
• Missing route handler

405 Method Not Allowed

The HTTP method is not supported for this endpoint:

DELETE /api/users HTTP/1.1

HTTP/1.1 405 Method Not Allowed
Allow: GET, POST

409 Conflict

The request conflicts with the current state of the server. Common for duplicate entries:

{
  "error": "Conflict",
  "message": "A user with email alice@example.com already exists",
  "status": 409
}

422 Unprocessable Entity

The request is well-formed but contains semantic errors. Common in validation:

{
  "error": "Unprocessable Entity",
  "message": "Validation failed",
  "errors": [
    {"field": "email", "message": "Invalid email format"},
    {"field": "age", "message": "Must be between 0 and 150"}
  ],
  "status": 422
}

429 Too Many Requests

Rate limiting — the client has sent too many requests in a given time period:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640000000

5xx — Server Errors

500 Internal Server Error

A generic server error. Something went wrong on the server side:

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred",
  "status": 500
}

Common causes:

• Unhandled exceptions
• Database connection failures
• Null pointer errors
• Configuration issues

502 Bad Gateway

The server, acting as a gateway or proxy, received an invalid response from an upstream server:

Common causes:

• Backend server is down
• Nginx/load balancer can't reach the application server
• Timeout from upstream server

503 Service Unavailable

The server is temporarily unable to handle the request, usually due to maintenance or overload:

HTTP/1.1 503 Service Unavailable
Retry-After: 3600

Common causes:

• Server maintenance
• Server overloaded
• Deployment in progress
• Database connection pool exhausted

504 Gateway Timeout

The server, acting as a gateway, didn't receive a timely response from the upstream server:

Common causes:

• Slow database queries
• External API timeout
• Long-running computations
• Network issues between servers

Best Practices for API Developers

1. Use the most specific status code — Don't return 200 for everything. Use 201 for creation, 204 for deletion, 422 for validation errors.

2. Include error details in the body — Status codes alone aren't enough. Return structured error messages.

3. Be consistent — Use the same error format across your entire API.

4. Don't expose internal details in production — Stack traces and database errors should only appear in development.

5. Use 429 with rate limiting headers — Always include Retry-After and rate limit headers.

Browse all status codes interactively with our HTTP Status Code Reference tool.