HTTP Status Codes

This URL has moved for good. Update your links.

Common causes

• A page was moved and a permanent redirect was configured for the old URL.
• A site enforces a canonical host, such as apex to www, or http to https.
• A trailing slash convention rewrites one URL form to the other.

What to do Nothing, if the redirect is intended. If you are the one linking, update the link to the target so the hop disappears: clients and crawlers both cache a 301, and a chain of them costs latency on every request.

Confused with 302 Found, 308 Permanent Redirect

This URL is temporarily somewhere else. Keep using the original.

Common causes

• A framework default redirect after a login or a form submission.
• A temporary maintenance page or A/B split.
• A legacy handler that was meant to be permanent but was never changed to 301.

What to do Decide whether the move is temporary. If it is permanent, return 301 or 308 instead, because a 302 tells search engines to keep indexing the original URL. If the method must survive the redirect, use 307.

Confused with 301 Moved Permanently, 307 Temporary Redirect

Nothing changed. Use the copy you already have in cache.

Common causes

• The client sent If-None-Match and the ETag still matches.
• The client sent If-Modified-Since and the resource has not changed.

What to do This is the success case for caching, not an error. If you are seeing stale content, the cause is the caching headers on the original response, not the 304 itself.

Confused with 200 OK, 412 Precondition Failed

The request itself is malformed and the server will not try to interpret it.

Common causes

• Malformed JSON, or a body that does not match the declared Content-Type.
• A query parameter of the wrong type, such as a word where a number is required.
• A header the server cannot parse, sometimes from a stray newline in a generated value.

What to do Log and inspect the raw request, not your intent for it. Most 400s come from a serialiser producing something slightly different from what you assumed. If the syntax is valid and only the content is wrong, the correct code is 422.

Confused with 422 Unprocessable Content

The server does not know who you are. Authenticate and try again.

Common causes

• No Authorization header was sent at all.
• A token has expired, or was signed with a key the server no longer accepts.
• The credentials are for a different environment than the one you are calling.

What to do Authenticate and retry. A correct 401 carries a WWW-Authenticate header telling you which scheme to use. If retrying with valid credentials still fails, the server means 403 and is using the wrong code.

Confused with 403 Forbidden

The server knows who you are and is refusing anyway.

Common causes

• The authenticated user lacks the role or scope the endpoint requires.
• A firewall, WAF, or bot rule rejected the request before it reached the application.
• The resource exists but belongs to another tenant or account.

What to do Logging in again will not help, so check permissions rather than credentials. If the server would rather not reveal that the resource exists, 404 is the deliberate alternative.

Confused with 401 Unauthorized, 404 Not Found

The server has no resource at that URL and will not say whether it ever did.

Common causes

• The path is wrong, often a typo or a stale link.
• The resource was deleted and nothing was left in its place.
• A route exists in development but was not deployed, or a rewrite rule is missing.

What to do Check the exact path, including case and trailing slash. If the resource genuinely used to exist and is gone for good, 410 is more informative to clients and crawlers. If it moved, 301 to the new URL.

Confused with 410 Gone, 403 Forbidden

The URL exists but not with that method. Check the Allow header.

Common causes

• A POST sent to an endpoint that only defines GET.
• A preflight or a proxy rewrote the method.
• A route matches the path but registers a different method.

What to do Read the Allow header in the response: a correct 405 must list the methods the URL does support.

Confused with 404 Not Found, 501 Not Implemented

The request clashes with the current state, such as an edit against a stale version.

Common causes

• Two writes to the same record raced and the second was based on stale data.
• A uniqueness constraint would be violated, such as an email that already exists.
• A state machine was asked for a transition that is not legal from its current state.

What to do Re-read the current state and decide whether to merge or abandon the write. Preventing the race is better than handling it: use conditional requests with ETags, which lets the server answer 412 before anything is written.

Confused with 412 Precondition Failed, 422 Unprocessable Content

Gone on purpose and not coming back. Stronger and rarer than 404.

Common causes

• Content was intentionally removed and the operator wants that stated.
• A time limited resource, such as an expired export or share link.

What to do Nothing to fix on the client. As an operator, prefer 410 over 404 when you know the resource is permanently gone: search engines drop a 410 faster than a 404.

Confused with 404 Not Found

Reserved and never to be implemented, because of the 1998 teapot joke.

Common causes

• A joke endpoint, or a server deliberately signalling that a route is a decoy.
• A framework that implemented the 1998 April Fools specification for fun.

What to do Nothing. IANA lists 418 as reserved precisely so no one can assign it a real meaning. Do not build behaviour on it.

The syntax is fine but the content is semantically wrong, such as a failed validation.

Common causes

• A field failed validation, such as a date in the past where a future date is required.
• The payload parses but references something that does not exist.
• A business rule rejected an otherwise well formed request.

What to do Return and read the per field errors: a 422 without a body explaining which field failed is a wasted response. Use 400 only when the request could not be parsed at all.

Confused with 400 Bad Request, 409 Conflict

You are being rate limited. Slow down and honour Retry-After.

Common causes

• A client loop firing requests without any backoff.
• A shared API key used by several services at once.
• A burst limit that is much lower than the advertised hourly limit.

What to do Honour the Retry-After header if it is present, and back off exponentially with jitter if it is not. Retrying immediately is the one response that reliably makes it worse.

Confused with 503 Service Unavailable

nginx closes the connection without sending any response at all.

Common causes

• A return 444 rule used to drop malicious or unwanted traffic silently.

What to do Nothing arrives at the client, so this shows up as a dropped connection rather than a status code. Check the nginx configuration for an explicit return 444.

Access is denied for legal reasons, such as a court order.

Common causes

• A takedown order or court injunction covering the content.
• A geographic block imposed to comply with local law.

What to do Nothing technical. The specification asks the server to explain the legal demand in the response body.

Confused with 403 Forbidden

The client hung up before nginx could send a response. Logged, never sent.

Common causes

• A user navigated away or refreshed while the request was still running.
• A client side timeout that is shorter than the server's own processing time.
• A load balancer in front of nginx cancelling the request first.

What to do A rise in 499s usually means responses got slower, not that clients got impatient. Compare the 499 rate against your response time percentiles before changing any timeouts.

Confused with 408 Request Timeout

The server hit an unexpected condition. This is the catch all failure.

Common causes

• An unhandled exception in application code.
• A failed database connection or a query that timed out.
• A missing environment variable or configuration value in a fresh deployment.

What to do This is the code that tells you least, so go to the server logs and the request ID. If the failure is a dependency rather than your own code, 502, 503, or 504 describe it far better to the caller.

Confused with 502 Bad Gateway, 503 Service Unavailable

The server acted as a gateway and got an invalid response from upstream.

Common causes

• The upstream process crashed or is not listening on the expected port.
• The upstream returned a response the proxy could not parse.
• A protocol mismatch, such as a proxy speaking HTTP to a TLS only backend.

What to do Check whether the upstream is running and reachable from the proxy, not from your laptop. A 502 always means the proxy reached a conclusion about the backend, so its logs name the backend.

Confused with 503 Service Unavailable, 504 Gateway Timeout

The server cannot handle the request right now: overload or maintenance.

Common causes

• A deliberate maintenance window.
• Autoscaling has not caught up with a traffic spike.
• A health check is failing and the load balancer has no healthy targets.

What to do Look at capacity and health checks rather than application code. A well behaved 503 carries Retry-After, which is what lets clients back off instead of hammering.

Confused with 500 Internal Server Error, 504 Gateway Timeout

The server acted as a gateway and upstream did not answer in time.

Common causes

• An upstream request that takes longer than the gateway timeout.
• A slow query or a lock in the database behind the service.
• A chain of services where each hop has its own, shorter, timeout.

What to do Compare the timeouts along the whole chain: the smallest one wins, and it is usually not the one you tuned. Then attack the slow work itself, because raising a timeout only moves the failure later.

Confused with 502 Bad Gateway, 408 Request Timeout

Cloudflare reached the origin but the answer made no sense to it.

Common causes

• The origin returned an empty response or an oversized header.
• The origin connection was reset mid response.

What to do Reproduce the request straight against the origin, bypassing Cloudflare, and compare the raw response. A 520 means the origin answered, so the origin logs have the request.

Cloudflare could not open a connection to the origin at all.

Common causes

• The origin service is stopped.
• A firewall at the origin is blocking Cloudflare's IP ranges.

What to do Check that the origin is listening, and that its firewall allows the Cloudflare address ranges.

Cloudflare's TCP connection attempt to the origin never completed.

Common causes

• The origin is overloaded and not accepting new connections.
• Packets are being dropped between Cloudflare and the origin.

What to do Look at connection level metrics at the origin rather than application logs: in a 522 the request never became an HTTP request.

Confused with 524 A Timeout Occurred

Cloudflare cannot route to the origin at all.

Common causes

• A DNS record points at an address that no longer exists.
• A routing or network configuration change at the origin.

What to do Verify that the origin DNS records resolve to an address that is actually live.

Cloudflare connected to the origin, but no response arrived in time.

Common causes

• A long running request that exceeds the proxy timeout.
• A slow database query or an external call inside the request.

What to do Move the slow work to a background job and answer immediately with a job identifier. Raising the timeout only delays the same failure.

Confused with 504 Gateway Timeout, 522 Connection Timed Out

The TLS handshake between Cloudflare and the origin did not complete.

Common causes

• The origin has no certificate for the requested hostname.
• No cipher suite is shared between the two ends.

What to do Check the origin certificate and the SSL mode configured in Cloudflare; a mismatch between the two is the usual cause.

Confused with 526 Invalid SSL Certificate

Cloudflare could not validate the origin's certificate.

Common causes

• The origin certificate has expired.
• The certificate is self signed while strict validation is switched on.

What to do Renew or replace the origin certificate, or switch the SSL mode to one that matches it.

Confused with 525 SSL Handshake Failed

Always paired with a Cloudflare 1xxx error that carries the real detail.

Common causes

• Any of the Cloudflare 1xxx conditions, which vary widely.

What to do Read the 1xxx code shown with the 530. The 530 alone carries no diagnosis and looking it up on its own is a dead end.