HTTP Status Codes

Complete reference for 2xx, 3xx, 4xx, and 5xx response codes

Overview

HTTP status codes are three-digit numbers returned by servers to indicate the result of a request. They are grouped into five classes based on the first digit. Understanding status codes is essential for proper error handling in your APIs.

1xx Informational - Request received, continuing process
2xx Success - Request successfully received and accepted
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 a valid request

2xx Success Codes

These codes indicate that the client's request was successfully received, understood, and accepted.

200

OK

The request has succeeded. The meaning depends on the HTTP method used.

When to use:
  • GET: Resource retrieved successfully
  • POST: Action completed successfully
  • PUT/PATCH: Resource updated successfully
HTTP/1.1 200 OK
Content-Type: application/json

{"id": 123, "name": "John Doe"}
201

Created

The request has been fulfilled and resulted in a new resource being created.

When to use:
  • POST: New resource created
  • PUT: Resource created at specified URI
HTTP/1.1 201 Created
Location: /api/users/124
Content-Type: application/json

{"id": 124, "name": "Jane Smith"}
202

Accepted

The request has been accepted for processing, but processing has not been completed. Used for async operations.

When to use:
  • Long-running operations
  • Batch processing jobs
  • Async task queues
HTTP/1.1 202 Accepted

{"status": "processing", "job_id": "abc123"}
204

No Content

The server successfully processed the request but is not returning any content.

When to use:
  • DELETE: Resource deleted successfully
  • PUT/PATCH: Update successful, no body needed
HTTP/1.1 204 No Content
// No response body
206

Partial Content

The server is delivering only part of the resource due to a range header sent by the client.

When to use:
  • File downloads with resume capability
  • Video/audio streaming

3xx Redirection Codes

These codes indicate that further action needs to be taken by the user agent to fulfill the request.

301

Moved Permanently

The requested resource has been permanently moved to a new URL. All future requests should use the new URL.

When to use:
  • URL structure changes
  • Domain migrations
  • Permanent API versioning changes
HTTP/1.1 301 Moved Permanently
Location: https://api.example.com/v2/users
302

Found (Temporary Redirect)

The requested resource temporarily resides under a different URI. Future requests should still use the original URI.

When to use:
  • Temporary maintenance
  • A/B testing
  • Load balancing
303

See Other

The response to the request can be found under another URI and should be retrieved using GET.

When to use:
  • After POST to redirect to result page
  • PRG (Post-Redirect-Get) pattern
304

Not Modified

The resource has not been modified since the last request. Used for caching.

When to use:
  • Conditional GET with If-Modified-Since
  • ETag validation
HTTP/1.1 304 Not Modified
ETag: "abc123"
// No response body
307

Temporary Redirect

Like 302 but guarantees that the method and body will not change when the redirected request is made.

308

Permanent Redirect

Like 301 but guarantees that the method and body will not change when the redirected request is made.

4xx Client Error Codes

These codes indicate that the client seems to have made an error. The request contains bad syntax or cannot be fulfilled.

400

Bad Request

The server could not understand the request due to invalid syntax.

When to use:
  • Malformed JSON
  • Invalid request parameters
  • Missing required fields
HTTP/1.1 400 Bad Request

{
  "error": "Bad Request",
  "message": "Invalid JSON format",
  "details": ["Expected ',' at position 45"]
}
401

Unauthorized

Authentication is required and has failed or has not been provided.

When to use:
  • Missing authentication token
  • Invalid or expired token
  • Invalid credentials
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer

{"error": "Unauthorized", "message": "Invalid or expired token"}
403

Forbidden

The server understood the request but refuses to authorize it. Unlike 401, authentication won't help.

When to use:
  • User lacks required permissions
  • Resource access not allowed
  • IP blocked or rate limited
HTTP/1.1 403 Forbidden

{"error": "Forbidden", "message": "You don't have permission to access this resource"}
404

Not Found

The server can not find the requested resource. The URL is not recognized.

When to use:
  • Resource doesn't exist
  • Invalid URL path
  • Deleted resource (optionally)
HTTP/1.1 404 Not Found

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

Method Not Allowed

The request method is known by the server but not supported by the target resource.

When to use:
  • DELETE on read-only resource
  • POST to collection-only endpoint
HTTP/1.1 405 Method Not Allowed
Allow: GET, POST

{"error": "Method Not Allowed", "message": "DELETE is not supported"}
409

Conflict

The request conflicts with the current state of the server.

When to use:
  • Duplicate resource (e.g., email already exists)
  • Version conflict
  • Resource state doesn't allow operation
HTTP/1.1 409 Conflict

{"error": "Conflict", "message": "Email already registered"}
410

Gone

The resource is no longer available and will not be available again.

When to use:
  • Permanently deleted resource
  • Deprecated API endpoints
422

Unprocessable Entity

The server understands the content type but was unable to process the contained instructions.

When to use:
  • Validation errors
  • Semantically incorrect data
  • Business rule violations
HTTP/1.1 422 Unprocessable Entity

{
  "error": "Validation Error",
  "details": [
    {"field": "email", "message": "Invalid email format"},
    {"field": "age", "message": "Must be 18 or older"}
  ]
}
429

Too Many Requests

The user has sent too many requests in a given amount of time (rate limiting).

When to use:
  • Rate limit exceeded
  • Quota exhausted
HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1623456789

{"error": "Too Many Requests", "retry_after": 60}

5xx Server Error Codes

These codes indicate that the server failed to fulfill an apparently valid request.

500

Internal Server Error

A generic error message when an unexpected condition was encountered.

When to use:
  • Unhandled exceptions
  • Server misconfiguration
  • Unknown server errors
HTTP/1.1 500 Internal Server Error

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred",
  "request_id": "abc123"
}
501

Not Implemented

The server does not support the functionality required to fulfill the request.

When to use:
  • Feature not yet implemented
  • Unsupported HTTP method
502

Bad Gateway

The server acting as a gateway received an invalid response from the upstream server.

When to use:
  • Upstream server down
  • Invalid upstream response
  • Proxy configuration error
503

Service Unavailable

The server is not ready to handle the request, usually due to maintenance or overload.

When to use:
  • Scheduled maintenance
  • Server overload
  • Temporary unavailability
HTTP/1.1 503 Service Unavailable
Retry-After: 3600

{"error": "Service Unavailable", "message": "System under maintenance"}
504

Gateway Timeout

The server acting as a gateway did not receive a timely response from the upstream server.

When to use:
  • Upstream server timeout
  • Long-running request timeout

Best Practices for Status Codes

🎯 Be Specific

Use the most specific status code that applies. Don't use 200 for everything or 500 for all errors.

📝 Include Error Details

Always return a response body with error details for 4xx and 5xx codes.

🔄 Be Consistent

Use the same status codes for the same situations across your entire API.

📖 Document Your Codes

Document which status codes each endpoint can return and what they mean in your context.

Related Topics

🔧 HTTP Methods

Learn which methods return which status codes.

⚠️ Error Handling

Design error responses for 4xx and 5xx codes.

🚦 Rate Limiting

Understand 429 Too Many Requests and Retry-After.

🔐 Authentication

Learn about 401 vs 403 and auth-related codes.