HTTP Status Codes: Complete Reference Guide

Published March 16, 2026 · 9 min read

HTTP status codes are three-digit numbers returned by a web server in response to a client's request. They tell you whether a request succeeded, was redirected, encountered an error, or something else entirely. Understanding these codes is essential for web development, API design, debugging, and SEO.

This complete reference covers every status code category with practical explanations. When building APIs, use our URL Encoder to properly encode query parameters and URLs.

Status Code Categories

1xx Informational Responses

• 100 Continue — The server received the request headers and the client should proceed to send the body. Used with large uploads when the client sends Expect: 100-continue.
• 101 Switching Protocols — The server agrees to switch protocols as requested by the client. Common when upgrading HTTP to WebSocket.
• 103 Early Hints — Used to return response headers before the final response, allowing the browser to preload resources like stylesheets and scripts.

2xx Success Codes

• 200 OK — The standard success response. The meaning varies by HTTP method: GET returns a resource, POST returns the result of the action, DELETE confirms removal.
• 201 Created — A new resource was successfully created. Typically returned after POST requests. Should include a Location header pointing to the new resource.
• 204 No Content — The request succeeded but there's no body to return. Common for DELETE and PUT responses, or when a form submission shouldn't redirect.
• 206 Partial Content — The server is delivering part of a resource due to a range header sent by the client. Used for resumable downloads and video streaming.

3xx Redirection Codes

• 301 Moved Permanently — The resource has permanently moved to a new URL. Search engines transfer ranking power (link equity) to the new URL. Use for permanent URL changes, domain migrations, and HTTPS upgrades.
• 302 Found — Temporary redirect. The resource is temporarily at a different URL, but the client should continue using the original URL for future requests.
• 304 Not Modified — The resource hasn't changed since the last request (based on If-Modified-Since or If-None-Match headers). The client should use its cached copy. Saves bandwidth.
• 307 Temporary Redirect — Like 302 but guarantees the HTTP method won't change. A POST stays a POST. Use when the redirect must preserve the request method.
• 308 Permanent Redirect — Like 301 but guarantees the HTTP method won't change. The permanent equivalent of 307.

4xx Client Error Codes

• 400 Bad Request — The server can't process the request due to malformed syntax, invalid parameters, or bad formatting. Common in APIs when JSON is invalid or required fields are missing.
• 401 Unauthorized — Authentication is required. The client must include valid credentials (API key, token, or login). Despite the name, this is about authentication, not authorization.
• 403 Forbidden — The server understands the request but refuses to authorize it. Unlike 401, re-authenticating won't help. The user simply doesn't have permission.
• 404 Not Found — The requested resource doesn't exist. The most recognized HTTP error. Can also be used intentionally to hide the existence of a resource for security.
• 405 Method Not Allowed — The HTTP method isn't supported for this URL. For example, sending POST to a read-only endpoint. The response should include an Allow header listing valid methods.
• 408 Request Timeout — The server timed out waiting for the request. The client took too long to send the complete request.
• 409 Conflict — The request conflicts with the current state of the resource. Common in APIs for duplicate entries, version conflicts, or business rule violations.
• 413 Payload Too Large — The request body exceeds the server's size limit. Often seen when uploading files that exceed the configured maximum.
• 429 Too Many Requests — Rate limiting. The client has sent too many requests in a given time period. Should include a Retry-After header indicating when to retry.

5xx Server Error Codes

• 500 Internal Server Error — A generic server-side error. Something went wrong, but the server can't be more specific. Check server logs for the actual cause.
• 502 Bad Gateway — The server acting as a gateway (like Nginx or a load balancer) received an invalid response from the upstream server. Often means the application server crashed or isn't running.
• 503 Service Unavailable — The server is temporarily unable to handle requests, usually due to maintenance or overload. Should include a Retry-After header when possible.
• 504 Gateway Timeout — The gateway server didn't receive a timely response from the upstream server. The application is running but taking too long to respond.

Best Practices for API Status Codes

1. Be specific: Use 201 for creation, 204 for no content, not 200 for everything.
2. Use 4xx for client mistakes: 400 for bad input, 422 for validation errors, 409 for conflicts.
3. Reserve 5xx for genuine server failures: Don't return 500 for invalid input.
4. Include helpful error bodies: Return JSON with error codes, messages, and field-level details.
5. Set proper headers: Retry-After for 429/503, Location for 201, Allow for 405.

Properly encode your API URLs and query parameters with our URL Encoder to avoid 400 errors from malformed requests.

Frequently Asked Questions

What is the difference between 401 and 403?

401 Unauthorized means the client hasn't provided valid authentication credentials — they need to log in or provide an API key. 403 Forbidden means the client is authenticated but doesn't have permission to access the resource. Re-authenticating won't help with a 403.

When should I use 301 vs 302 redirect?

Use 301 Moved Permanently when a URL has permanently changed — this transfers SEO value to the new URL. Use 302 Found for temporary redirects where the original URL will be used again, like during maintenance or A/B testing.

What causes a 502 Bad Gateway error?

A 502 occurs when a reverse proxy (like Nginx) receives an invalid response from the backend application server. Common causes include the application crashing, not running, timing out, or returning malformed responses. Check application logs and ensure the backend service is running.

How do I fix a 429 Too Many Requests error?

429 means you've exceeded the API's rate limit. Check the Retry-After response header for when to retry. Implement exponential backoff in your code, cache responses to reduce requests, and consider requesting a higher rate limit from the API provider.

What is the difference between 500 and 503 errors?

500 Internal Server Error indicates an unexpected condition that the server can't handle — typically a bug in the code. 503 Service Unavailable means the server is temporarily unable to handle requests due to maintenance or overload, and the condition is expected to be temporary.