HTTP Status Codes: Complete Reference Guide

HTTP status codes are the language servers use to communicate the result of every request. A 200 means success, a 404 means not found, a 500 means something broke. This guide covers every major status code — what it means, when to expect it, and how to handle it in production APIs and web applications.

How HTTP Status Codes Work

Every HTTP response includes a three-digit status code. The first digit defines the category:

• 1xx — Informational: Request received, continuing process
• 2xx — Success: Request was received, understood, and accepted
• 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 an apparently valid request

For monitoring purposes, 4xx codes usually indicate client-side issues (wrong URL, missing auth), while 5xx codes indicate server-side failures that your team needs to respond to immediately.

2xx Success Codes

2xx codes confirm the request was processed successfully. The specific code communicates what happened:

200 OK

The most common success code. The request succeeded. For GET requests, the resource is included in the response body. For POST/PUT requests, the action was completed.

201 Created

A new resource was successfully created, typically in response to a POST request. The Location header should include the URL of the newly created resource. Always use 201 (not 200) when your API creates a new record.

202 Accepted

The request was accepted for processing, but processing hasn't completed. Used for asynchronous operations where the work happens in the background (e.g., sending an email, processing a video). Return a job ID so the client can check status.

204 No Content

The request succeeded but there's nothing to return. Common for DELETE operations or updates where the client doesn't need the updated resource returned. The response body must be empty.

206 Partial Content

The server is returning only part of the resource, as requested by a Range header. Used for large file downloads, video streaming, and resumable downloads.

3xx Redirection Codes

3xx codes tell the client that additional action is required, usually following a redirect to a different URL.

301 Moved Permanently

The resource has permanently moved to a new URL (in the Location header). Clients should update their bookmarks and future requests should use the new URL. Search engines transfer ranking signals from the old URL to the new one. Use for permanent URL changes.

302 Found (Temporary Redirect)

The resource is temporarily at a different URL. Unlike 301, clients should continue using the original URL for future requests. Often misused when 301 is more appropriate.

304 Not Modified

The resource hasn't changed since the version in the client's cache (checked via If-Modified-Since or ETag headers). The response body is empty — the client should use its cached version. Reduces bandwidth significantly for repeat requests.

307 Temporary Redirect

Similar to 302, but explicitly preserves the HTTP method. If you POST to a URL that returns 307, the client should POST to the new URL too. 302 implementations often incorrectly change POST to GET.

308 Permanent Redirect

Like 301, but preserves the HTTP method. Use 308 instead of 301 when the original request was a POST/PUT and the method should be preserved at the new URL.

4xx Client Error Codes

4xx errors indicate a problem with the request. The client made an error — wrong URL, missing authentication, invalid data. These are expected errors that clients should handle gracefully. High 4xx rates in your API logs often indicate integration bugs or attack traffic.

400 Bad Request

The server can't process the request due to malformed syntax, invalid parameters, or deceptive routing. The most generic client error. Always include a descriptive error message in the response body so developers can debug.

401 Unauthorized

The request lacks valid authentication credentials. Despite the name, this is about authentication (proving who you are), not authorization (permission to act). The response should include a WWW-Authenticate header indicating how to authenticate.

403 Forbidden

The server understood the request but refuses to authorize it. Unlike 401, re-authenticating won't help — the client doesn't have permission. Use when a user is authenticated but lacks the required role or permission to access a resource.

404 Not Found

The most famous status code. The server couldn't find the requested resource. Could mean the resource never existed, has been deleted, or the URL is wrong. APIs should return 404 for requests to non-existent resources, not 400 or 200.

405 Method Not Allowed

The HTTP method used is not supported for this endpoint. For example, sending a DELETE request to a read-only resource. The response must include an Allow header listing the supported methods.

409 Conflict

The request conflicts with the current state of the resource. Common scenarios: trying to create a user with an email that already exists, concurrent updates to the same record, or a resource being in the wrong state for the requested operation.

410 Gone

Like 404, but permanent — the resource is gone and won't come back. Use 410 when you deliberately remove a resource (e.g., a user deletion). Search engines will remove the URL from their index faster with 410 than 404.

422 Unprocessable Entity

The request is well-formed but contains semantic errors. Used when validation fails on the request body. For example, a POST to create a user passes JSON parsing but the email field contains an invalid email address. The response body should list all validation errors.

429 Too Many Requests

Rate limiting in action. The client has sent too many requests in a given time period. Include Retry-After and X-RateLimit-Reset headers. Clients should implement exponential backoff when they receive 429 responses.

5xx Server Error Codes

5xx codes indicate a server-side failure. These are your responsibility to fix. Every 5xx error in production should be monitored, logged, and investigated. A spike in 5xx errors is a sign of an active incident.

500 Internal Server Error

The generic server error. The server encountered an unexpected condition that prevented it from fulfilling the request. This is almost always a bug in your code — an unhandled exception, a null pointer dereference, or an unexpected input state.

In production: Never expose stack traces in 500 responses — they leak implementation details. Log the full error server-side and return a generic message to the client.

501 Not Implemented

The server doesn't support the functionality required to fulfill the request. Different from 405 (method not allowed for this resource) — 501 means the server doesn't support this HTTP feature at all. Rarely used.

502 Bad Gateway

The server, acting as a gateway or proxy, received an invalid response from the upstream server. Common causes: the backend application crashed, the upstream server is returning garbage, or there's a network issue between the proxy and the backend. Usually indicates a problem with your backend service or infrastructure.

503 Service Unavailable

The server is temporarily unable to handle requests, typically due to:

• Server overload (too many concurrent requests)
• Scheduled maintenance
• Dependent service (database, cache) being unavailable
• During deployment (brief window when new processes start)

Unlike 500, 503 implies the condition is temporary. Include a Retry-After header when you know when service will resume.

504 Gateway Timeout

Similar to 502, but the upstream server timed out before returning a response. The gateway gave up waiting. Common causes: slow database queries, overloaded backend services, or network latency between services.

504s often appear before 503s — when load increases, requests get slow (504) before the service collapses entirely (503). Monitoring 504 rates can give you early warning of capacity issues.

507 Insufficient Storage

The server can't store the representation needed to complete the request. Typically used in WebDAV but can apply when disk space runs out on file upload services.

508 Loop Detected

The server detected an infinite loop while processing the request. WebDAV-specific, used when circular references are found in a depth-infinity request.

1xx Informational Codes

1xx codes are rarely encountered in application code but are important in infrastructure contexts.

100 Continue

The server has received the request headers and the client should proceed to send the request body. Used with the Expect: 100-continue request header to avoid sending large bodies to servers that would reject them.

101 Switching Protocols

The server is switching protocols as requested by the client. Used when upgrading HTTP connections to WebSockets — you'll see 101 Switching Protocols in successful WebSocket handshakes.

102 Processing

WebDAV extension. The server has received and is processing the request, but no response is available yet. Prevents client timeout during long operations.

103 Early Hints

Allows the server to send preliminary headers (like Link preload hints) before the final response is ready. Modern browsers use these hints to start loading resources before the main response arrives, improving page load performance.

Monitoring HTTP Status Codes in Production

Understanding status codes is one thing — tracking them in production is another. Here's how to monitor effectively:

Which Codes to Alert On

• 5xx rate > 1%: Warning. Investigate immediately.
• 5xx rate > 5%: Critical. Active incident.
• 503 rate > 0%: Warning. Service availability degraded.
• 504 rate spike: Warning. Upstream services getting slow.
• 401 rate spike: Investigate — may indicate credential rotation issue or attack.
• 429 rate spike: Investigate — rate limit misconfiguration or traffic spike.

Error Budget Impact

Each 5xx response consumes your error budget. If your SLO is 99.9% availability, you can afford roughly 1 error per 1,000 requests in a 30-day window before breaching your target. Track error rates per endpoint to identify which parts of your API are most fragile.

Key Metrics to Track

• Error rate by status class: 4xx% and 5xx% over time
• Error rate by endpoint: Which routes are failing most?
• 4xx:5xx ratio: High 4xx but low 5xx = client integration bugs. High 5xx = server bugs.
• Top error codes: What are your most common specific codes?
• Error trends: Are errors increasing over time?

Structured Error Responses

When returning 4xx or 5xx errors, always include a structured error body. This helps client developers debug and helps your logging infrastructure parse errors automatically:

The request_id field is especially important — it lets users report errors to your support team, who can look up the full context in your logs.

HTTP Status Code Best Practices for APIs

Be Specific

Return the most specific code that applies. Don't default to 400 for everything — use 401, 403, 404, 409, 422 where appropriate. Specific codes help clients handle errors correctly without parsing error messages.

Never Return 200 for Errors

Some older APIs return 200 with an error message in the body. This breaks monitoring tools, HTTP clients, and any system that relies on status codes. Always use the correct non-2xx code for errors.

Include Retry Headers for 429 and 503

When you rate limit (429) or go into maintenance mode (503), always include a Retry-After header with the number of seconds to wait before retrying. This prevents clients from hammering you immediately after they back off.

Use 404 vs 403 Carefully for Security

Returning 403 on a resource a user doesn't have access to reveals that the resource exists. For sensitive resources, consider returning 404 instead — it gives away less information about your data model. This is called a "security through obscurity" tradeoff — choose based on your threat model.

Quick Reference: Most Common Status Codes

Key Takeaways

• 2xx: Success — request processed correctly
• 3xx: Redirection — client needs to follow up with another request
• 4xx: Client error — the request is wrong; the client should fix it before retrying
• 5xx: Server error — your service failed; investigate immediately
• Always return the most specific code applicable — don't default to generic 400/500
• Include Retry-After headers on 429 and 503 responses
• Monitor error rates by status class in production; alert on 5xx spikes
• Never expose internal details (stack traces, SQL errors) in 5xx responses

HTTP status codes form the backbone of how APIs communicate state. Using them correctly makes your API easier to integrate with, debug, and monitor. When every endpoint returns the right code, your monitoring stack can automatically distinguish client bugs from server failures — saving you hours of investigation during incidents.