HTTP Status Codes Reference

1xx Informational 4 codes ▼

100

Continue

The server has received the request headers and the client should proceed to send the body. Used with large uploads when the client sends Expect: 100-continue first.

101

Switching Protocols

The server is switching protocols as requested by the client. Used when upgrading from HTTP to WebSocket connections.

Common in WebSocket handshakes — browser sends Upgrade: websocket, server replies 101.

102

Processing

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

103

Early Hints

Sent before the final response to allow the client to start preloading resources (CSS, JS, fonts) while the server prepares the full response. Improves page load performance.

Supported by major CDNs. Use Link: </style.css>; rel=preload headers in the 103 response.

2xx Success 9 codes ▼

200

OK

The most common success code. The request succeeded. The response body contains the requested resource (GET) or confirmation of the action (POST, PUT, etc.).

201

Created

A new resource was successfully created. The response usually includes a Location header pointing to the new resource.

REST APIs return 201 after POST requests that create a new record. Include the new resource's URL in Location.

202

Accepted

The request has been accepted for processing, but processing has not been completed (or may not have started). Used for async / background jobs.

Useful for slow operations: return 202 immediately, then poll a job status endpoint.

203

Non-Authoritative Information

The response was returned successfully, but the metadata came from a local or third-party copy rather than the origin server (e.g. modified by a proxy).

204

No Content

The request succeeded but there's nothing to return. The response has no body. Common after DELETE requests or after updates where no data needs to be returned.

CORS preflight OPTIONS requests typically get a 204. Also common for save/update endpoints where you don't need to return the updated resource.

205

Reset Content

The server processed the request successfully. The client should reset the document view (e.g. clear a form after submission).

206

Partial Content

The server is returning only part of the requested resource. Used when the client sends a Range header (e.g. resumable downloads, video streaming).

Video players use 206 to stream chunks. Download managers use it to resume interrupted downloads.

207

Multi-Status

A WebDAV extension. The response body contains multiple separate response codes for multiple sub-requests in a single XML body.

226

IM Used

Used in HTTP delta encoding. The server has fulfilled a GET request and the response is a representation of the instance manipulation applied to the current instance.

3xx Redirection 8 codes ▼

300

Multiple Choices

The request has more than one possible response. The client or user should choose one. Rarely used in practice.

301

Moved Permanently

The requested URL has permanently moved to a new URL (in the Location header). Search engines update their index. Clients should use the new URL for future requests.

Use 301 for permanent URL changes (domain migration, removing www). Search engines pass link equity. Browsers cache this redirect indefinitely.

302

Found (Temporary Redirect)

The resource temporarily lives at a different URL. Clients should continue using the original URL for future requests. Search engines don't update their index.

Browsers often change POST to GET on 302 redirect. Use 307 to preserve the HTTP method.

303

See Other

The response to the request is found at another URL using GET. Used to redirect after a POST so refreshing doesn't resubmit the form (the Post/Redirect/Get pattern).

The classic fix for "are you sure you want to resubmit this form?" browser warnings. After POST, redirect with 303 to a GET confirmation page.

304

Not Modified

The resource hasn't changed since the client's cached version. No body is returned. The client should use its cached copy. Reduces bandwidth.

The server compares the client's If-None-Match (ETag) or If-Modified-Since header. A 304 means "your cache is still good."

307

Temporary Redirect

Like 302, but the HTTP method must not be changed. A POST request is redirected as a POST, not silently downgraded to GET.

Prefer 307 over 302 for API redirects to ensure POST/PUT/PATCH methods are preserved.

308

Permanent Redirect

Like 301, but the HTTP method must not be changed. A POST is redirected as a POST. The new URL should be used permanently.

Use 308 instead of 301 when permanently moving API endpoints that receive POST/PUT/PATCH requests.

4xx Client Errors 18 codes ▼

400

Bad Request

The server couldn't understand the request due to invalid syntax, missing required fields, or malformed data. The client should not repeat the request without modification.

Return 400 with a clear error body explaining what's wrong: {"error": "email field is required"}

401

Unauthorized

Authentication is required and has failed or not been provided. Despite the name, this is an authentication error (not authorization). The client should authenticate and retry.

401 = "Who are you?" (not logged in). 403 = "I know who you are, but no." Always include WWW-Authenticate header.

402

Payment Required

Reserved for future use. Originally intended for digital payment systems. Some APIs use it informally to indicate a paywall or usage limit reached.

Not officially standardized, but used by some APIs (e.g. "you've hit your free tier limit") and some developers use it for rate limiting paid tiers.

403

Forbidden

The client is authenticated but does not have permission to access the resource. Unlike 401, authenticating won't help — the user simply doesn't have access.

401 = not logged in. 403 = logged in but not allowed. Some APIs return 404 instead to hide the existence of the resource.

404

Not Found

The server can't find the requested resource. The URL may be wrong, the resource may have been deleted, or it may never have existed.

APIs sometimes deliberately return 404 instead of 403 to avoid revealing that a resource exists but is private. A 404 is cacheable.

405

Method Not Allowed

The HTTP method used (GET, POST, PUT, DELETE, etc.) is not allowed for this endpoint. The response must include an Allow header listing valid methods.

Common mistake: sending a POST to a GET-only endpoint. Check your API docs for which methods each endpoint supports.

406

Not Acceptable

The server can't produce a response matching the client's Accept headers (content type, language, encoding). The server can't satisfy the request format.

408

Request Timeout

The server timed out waiting for the request. The client took too long to send the complete request. The client may retry the request.

409

Conflict

The request conflicts with the current state of the resource. Common causes: trying to create a resource that already exists, version conflicts, or concurrent modification.

Return 409 when trying to register with an email that's already taken, or when optimistic locking detects a version conflict.

410

Gone

The resource previously existed but has been permanently deleted and won't be coming back. Unlike 404, this explicitly signals permanent deletion. Search engines de-index the URL.

Use 410 for intentionally removed pages to tell search engines to stop indexing them. More explicit than 404.

411

Length Required

The server requires a Content-Length header in the request but none was provided.

413

Payload Too Large

The request body exceeds the server's size limits. Common when uploading files that exceed the max upload size configured on the server.

Nginx default is 1MB. Increase with client_max_body_size 10m; in your config. S3 multipart upload avoids this for large files.

414

URI Too Long

The URL is longer than the server can process. Usually caused by a client converting POST data to a GET request with a very long query string.

415

Unsupported Media Type

The request's Content-Type is not supported by the server for this endpoint. The payload format isn't what the server expects.

Sending form data when the endpoint expects JSON? You'll get 415. Add Content-Type: application/json header.

422

Unprocessable Entity

The request is syntactically correct (valid JSON/XML) but semantically invalid. Validation failed. The body can be parsed but contains logical errors.

Rails returns 422 for failed model validations. Many REST APIs prefer 422 over 400 for validation errors since the format was valid but the data wasn't.

429

Too Many Requests

The client has sent too many requests in a given time window (rate limiting). The response should include Retry-After to tell the client when to try again.

Include X-RateLimit-Limit, X-RateLimit-Remaining, and Retry-After headers. Exponential backoff is the correct client behavior.

451

Unavailable For Legal Reasons

The resource is not available for legal reasons — censorship, DMCA takedown, court order, etc. Named after Ray Bradbury's Fahrenheit 451.

A rare but meaningful code. More honest than returning 403 when content is blocked by legal requirement.

5xx Server Errors 10 codes ▼

500

Internal Server Error

The server encountered an unexpected condition that prevented it from fulfilling the request. The generic catch-all for server-side exceptions. Something crashed.

Check your server logs. This is a bug in your code. Never leak stack traces to the client — log them server-side.

501

Not Implemented

The server doesn't support the functionality needed to fulfill the request. Often means the HTTP method used is not supported by the server at all.

502

Bad Gateway

The server, acting as a gateway or proxy, received an invalid response from an upstream server. Your application server is down or returning garbage.

Nginx returning 502? Your app server (Node, Gunicorn, etc.) is probably crashed, not running, or not reachable. Check systemctl status on your app.

503

Service Unavailable

The server is temporarily unable to handle requests — overloaded, under maintenance, or restarting. The client should retry after some time. Include Retry-After if possible.

Best practice: return 503 with a Retry-After header during planned maintenance. Load balancers remove servers returning 503 from rotation.

504

Gateway Timeout

The server, acting as a gateway, didn't receive a timely response from an upstream server. Like 502, but the problem is a timeout rather than an invalid response.

Nginx returning 504? Your app is responding too slowly. Increase proxy_read_timeout or optimize the slow operation. Consider async processing for long jobs.

505

HTTP Version Not Supported

The server doesn't support the HTTP protocol version used in the request. Rare in modern deployments.

507

Insufficient Storage

A WebDAV extension. The server cannot store the representation needed to complete the request — typically a full disk or storage quota exceeded.

508

Loop Detected

A WebDAV extension. The server detected an infinite loop while processing the request. A resource binds to itself recursively.

511

Network Authentication Required

The client needs to authenticate to gain network access. Used by captive portals (hotel Wi-Fi, airport Wi-Fi) that intercept requests before granting access.

That hotel Wi-Fi login page that hijacks all your HTTP traffic? That's how 511 is supposed to work — though most portals just redirect instead.

5xx+

Cloudflare / CDN Error Codes

Cloudflare uses non-standard 5xx codes: 520 (unknown error from origin), 521 (origin refused connection), 522 (connection timed out), 523 (origin unreachable), 524 (timeout), 525 (SSL handshake failed), 526 (invalid SSL cert).

These only appear when Cloudflare is in front of your server. They're Cloudflare's diagnostic codes, not standard HTTP.