HTTP Status Codes Every Web Developer Should Understand

A browser can display a page while the server quietly returns the wrong HTTP status code.

This creates confusing situations. A missing page may look like a normal error page but return 200 OK. A temporary redirect may remain active for years. A maintenance page may return the same response as a permanently deleted resource.

HTTP status codes explain what happened when a client requested a resource.

Developers should understand these codes because they affect browsers, APIs, monitoring systems, search crawlers, caching, redirects, and error handling.

This guide covers the status codes that matter most when building and maintaining a website.

What Is an HTTP Status Code?

An HTTP status code is a three-digit number returned by a server in response to a request.

The first digit identifies the general response category:

• 1xx — Informational response
• 2xx — Successful request
• 3xx — Redirection
• 4xx — Client-side request problem
• 5xx — Server-side failure

The status code is only one part of the response. Headers and the response body provide additional information.

You can inspect the response headers from a terminal:

curl -I https://example.com/page

A result might begin with:

HTTP/2 200

This tells you that the request was successful and the server used HTTP/2 for the response.

200 OK

200 OK indicates that the request succeeded.

For an ordinary web page, this generally means the server found the requested resource and returned its content.

Common uses include:

• Homepage
• Article
• Product page
• Documentation
• Successful API request
• Search results
• Category page

A page should not return 200 OK simply because the server produced some HTML.

If the requested resource does not exist, returning a normal-looking error page with a 200 response can confuse monitoring tools, crawlers, and developers.

Always match the status code with the actual outcome.

201 Created

201 Created indicates that a request successfully created a new resource.

It is commonly used by APIs after operations such as:

• Creating a user
• Publishing a record
• Uploading a resource
• Creating an order
• Adding a database entry

The response may include the location of the newly created resource.

For example, an API creating a project might return a location such as:

Location: /projects/123

A normal page loaded through a browser usually returns 200, while successful resource creation through an API may return 201.

204 No Content

204 No Content means that the request succeeded but the server is not returning a response body.

This can be appropriate for:

• Successful deletion
• Saving a setting without returning data
• Updating a record when no response content is needed
• Certain background API operations

It is usually inappropriate for an ordinary navigational page because the browser expects content to display.

Do not use 204 merely to hide an application error.

301 Moved Permanently

301 Moved Permanently tells clients that a resource has a new permanent location.

Example:

/old-documentation
    → /docs

Appropriate situations include:

• A page has permanently moved.
• A URL structure has changed.
• Two pages have been consolidated.
• A website has migrated to HTTPS.
• An outdated path has a clear replacement.

The redirect destination should be relevant to the original resource.

Redirecting every deleted page to the homepage creates a confusing experience. Visitors expected a specific resource, not a general landing page.

Update internal links so they point directly to the final destination instead of relying on the redirect.

302 Found

302 Found is commonly used for temporary redirects.

It tells the client that the resource is temporarily available at another location.

Possible uses include:

• Temporary campaign destination
• Short maintenance workflow
• Location-based experience
• Temporary application state
• Testing a replacement page

A temporary redirect should not remain in place simply because nobody remembered to review it.

If the destination has become permanent, evaluate whether a permanent redirect is more appropriate.

303 See Other

303 See Other directs the client to retrieve another resource, usually with a GET request.

It is useful after submitting a form.

For example:

1. A visitor submits a form with POST.
2. The server processes the request.
3. The server returns 303.
4. The browser loads a confirmation page with GET.

This helps prevent accidental form resubmission when the visitor refreshes the confirmation page.

307 Temporary Redirect

307 Temporary Redirect represents a temporary redirect while preserving the original request method.

If the original request used POST, the redirected request should continue using POST.

This differs from common historical behavior associated with some 302 implementations, where clients may change the method.

Use 307 when method preservation is important and the redirect is temporary.

308 Permanent Redirect

308 Permanent Redirect is a permanent redirect that preserves the request method.

It can be useful when:

• An API endpoint has permanently moved.
• A permanent route change must preserve POST, PUT, or another method.
• Request bodies need to reach the new destination unchanged.

For ordinary GET pages, developers frequently use 301. For method-sensitive permanent redirects, 308 can communicate the intended behavior more precisely.

Redirect Chains

A redirect chain occurs when one URL redirects through multiple locations:

/page-a
    → /page-b
    → /page-c
    → /final-page

Each additional step creates another request.

Chains can increase latency, complicate debugging, and create more places for a redirect to fail.

Update the original redirect where possible:

/page-a
    → /final-page

Also update internal links so they reference /final-page directly.

Redirect Loops

A redirect loop occurs when URLs redirect repeatedly without reaching a final resource.

Example:

/login
    → /account
    → /login

Browsers eventually stop following the redirects and display an error.

Common causes include:

• Conflicting HTTP-to-HTTPS rules
• Incorrect authentication checks
• Reverse-proxy configuration
• Domain normalization errors
• Trailing-slash rules
• Caching
• Application and server redirects fighting each other

Inspect the complete redirect path instead of testing only the first response.

You can use:

curl -IL https://example.com/page

The -L option follows redirects so you can review the chain.

400 Bad Request

400 Bad Request means that the server could not process the request because it was malformed or invalid.

Possible causes include:

• Invalid syntax
• Incorrect request data
• Missing required values
• Invalid JSON
• Unsupported parameter format
• Damaged request body

An API should provide a clear error response explaining which input was invalid without exposing sensitive server information.

401 Unauthorized

Despite its name, 401 Unauthorized generally means that authentication is required or has failed.

It may occur when:

• No credentials were supplied.
• A token has expired.
• Login information is invalid.
• An authentication header is missing.
• The session is no longer valid.

A 401 response should help the client understand how authentication can be provided.

Do not include secret tokens, passwords, or sensitive internal details in the error response.

403 Forbidden

403 Forbidden means the server understood the request but refuses to authorize access.

The user may already be authenticated but lack permission.

Examples include:

• A normal user requests an administrator page.
• An account attempts to access another customer’s resource.
• A regional or policy restriction blocks the request.
• File permissions prevent access.
• A security rule denies the operation.

The distinction between 401 and 403 is important:

• 401 commonly means authentication is required or failed.
• 403 commonly means access is not permitted.

Avoid revealing information that could help someone identify private resources.

404 Not Found

404 Not Found means the server could not find the requested resource.

Common causes include:

• Mistyped URL
• Deleted page
• Broken internal link
• Incorrect route
• Missing file
• Old bookmark
• Invalid identifier

A helpful 404 page should:

• Clearly explain that the resource was not found
• Provide navigation
• Offer search where appropriate
• Link to the homepage
• Match the website design
• Return the actual 404 status

Do not automatically redirect every 404 request to the homepage. This hides the problem and confuses visitors.

Soft 404 Errors

A soft 404 occurs when a page behaves like a missing page but returns a successful status such as 200 OK.

For example, the page may display:

We could not find the product you requested.

But the server returns:

HTTP/2 200

The visible message and server response contradict each other.

Fix the route so genuinely missing resources return an appropriate missing-resource status.

This makes monitoring, debugging, and automated processing more reliable.

410 Gone

410 Gone indicates that a resource was intentionally removed and is not expected to return.

It may be appropriate when:

• A resource was permanently withdrawn.
• A temporary page has expired.
• Content was deliberately deleted.
• An API resource is no longer available.
• There is no suitable replacement.

If a relevant replacement exists, a redirect may provide a better experience.

If no replacement exists and the removal is intentional, 410 communicates that situation clearly.

429 Too Many Requests

429 Too Many Requests indicates that the client has sent too many requests within a period.

This response is commonly used for rate limiting.

It can help protect:

• Login endpoints
• APIs
• Search functions
• Form submissions
• Resource-intensive operations
• Public data endpoints

The server may include information indicating when the client can try again.

Rate limits should be documented clearly for legitimate API users. Avoid returning a generic server error when the real issue is request frequency.

500 Internal Server Error

500 Internal Server Error means the server encountered an unexpected problem.

Possible causes include:

• Unhandled exception
• Application bug
• Invalid server configuration
• Database failure
• Missing dependency
• File permission problem
• Unexpected data

The public response should not expose:

• Stack traces
• Database credentials
• File-system paths
• Environment variables
• Secret keys
• Private application details

Detailed information should be recorded securely in server logs for authorized developers.

502 Bad Gateway

502 Bad Gateway commonly occurs when a gateway or proxy receives an invalid response from an upstream server.

This can involve:

• Reverse proxy
• Application server
• Load balancer
• CDN
• Container service
• External API

Troubleshooting may require checking both the public-facing server and the upstream service.

Confirm that the upstream application is running, reachable, and responding with a valid protocol.

503 Service Unavailable

503 Service Unavailable means the service is temporarily unable to handle the request.

Appropriate uses include:

• Planned maintenance
• Temporary overload
• Application startup
• Dependency outage
• Capacity problem

A maintenance page should return 503, not 200, when the real service is temporarily unavailable.

The response may indicate when the client should try again.

Do not leave a 503 response active after the service has recovered.

504 Gateway Timeout

504 Gateway Timeout indicates that a gateway or proxy did not receive a response from an upstream service within the expected time.

Possible causes include:

• Slow database query
• Unresponsive application process
• Network problem
• Overloaded upstream server
• Slow external API
• Incorrect timeout settings

Increasing the timeout may hide the symptom without fixing the cause.

Measure the slow operation and determine why the upstream service cannot respond in time.

Status Code Testing Checklist

Before deployment, verify that:

• Working pages return an appropriate successful response.
• New resources return the expected creation response.
• Permanent redirects use an appropriate permanent status.
• Temporary redirects are reviewed regularly.
• Redirect chains are minimized.
• Redirect loops do not exist.
• Authentication failures return an appropriate response.
• Permission failures do not expose private information.
• Missing resources return 404.
• Permanently removed resources are handled intentionally.
• Rate limits return a clear response.
• Server errors do not expose sensitive details.
• Maintenance pages return a temporary-unavailable response.
• Proxy and upstream failures are monitored separately.
• Custom error pages match their HTTP status codes.

Final Thoughts

HTTP status codes are part of the contract between a server and its clients.

A beautiful error page with the wrong status is still technically incorrect. A working redirect that passes through several unnecessary locations is still inefficient. A generic server error can hide an authentication, permission, or rate-limiting problem.

Choose status codes based on the actual result of the request.

Test them from the browser, terminal, application logs, monitoring systems, and automated tests. Clear responses make websites easier to maintain and failures easier to diagnose.