What is the difference between 401 and 403?

401 means authentication is missing or invalid, so supplying valid credentials should fix it. 403 means the server knows who you are and is still refusing, so authenticating again will not help; the account lacks the permission. In practice, if refreshing a token resolves it, it was a 401 situation.

What causes a 502 Bad Gateway?

A proxy or load balancer received an invalid or empty response from the service behind it. Usually that service has crashed, is not running, or returned something unparseable. Check the upstream application first, then the proxy configuration; the client that saw the 502 is almost never the problem.

How is 504 different from 502?

Both come from a gateway, but 502 means the upstream answered badly while 504 means it did not answer in time. A 504 points at latency: a slow query, an overloaded service, or a proxy timeout set lower than the work actually takes.

Should I use 301 or 302 for a redirect?

301 when the move is permanent and you want search engines and browsers to update. Be careful: browsers cache 301s aggressively and users who have received one may keep following it even after you change your mind. Use 302 or 307 for anything temporary, and 307 or 308 when the HTTP method must be preserved.

When should an API return 422 rather than 400?

400 for a request the server cannot parse, such as malformed JSON or a missing required parameter. 422 for a request that parsed correctly but failed business validation, such as an email address in the wrong format. The distinction tells the client whether to fix its serialisation or its data.

What does 429 mean and how should I handle it?

You have exceeded a rate limit. The response usually carries Retry-After telling you how long to wait. Respect it, and implement exponential backoff rather than retrying immediately, since a tight retry loop against a rate limiter makes the situation worse for everyone.

Is it acceptable to return 200 with an error in the body?

It is common and it is a mistake. Monitoring, caching, retry logic and client libraries all act on the status code, and reporting success for a failure blinds all of them. Use the status code to say what happened and the body to explain the detail.

What is 418, and is it real?

I am a teapot, defined in RFC 2324 as an April Fools joke in 1998. It is not a real status code, though it appears as an easter egg in a number of servers and frameworks, and there was a minor campaign to keep it when its removal was proposed.

What should I return after a successful DELETE?

204 No Content is the conventional answer, since there is nothing meaningful to return. 200 with a body is acceptable if you have something useful to say. Returning 404 for deleting something already deleted is a design choice: many APIs return 204 regardless, treating delete as idempotent.

Is anything I search for sent to a server?

No. The whole reference ships with the page, so searching happens in your browser with no request, and it continues to work offline.

HTTP Status Codes – What They Mean and How to Fix Them

HTTP Status Codes

52 results

// HTTP Status Codes: Features

Three answers, not one

Knowing that 502 means Bad Gateway does not help anyone. The useful information is that a proxy received an invalid response from the service behind it, which means the thing to check is whether that upstream service is running. Every code here carries a description, the causes that actually produce it, and the action to take, because the definition on its own almost never resolves the problem you have.

The classes, and what they tell you

The first digit says whose problem it is, which is the fastest triage available. 1xx is informational and rarely seen. 2xx means it worked. 3xx means look elsewhere. 4xx means the client sent something the server will not accept, so the fix is in the request. 5xx means the server failed while handling a request that may have been perfectly valid, so the fix is on the server. Getting this distinction right saves a great deal of time before you have read a single log line.

The pairs that are routinely confused

401 and 403: the first means you have not proved who you are, the second means you have and it is still not allowed, so re-authenticating will not help. 502 and 504: the first means the upstream answered badly, the second that it did not answer in time. 301 and 302: the first is permanent and gets cached aggressively by browsers and search engines, so shipping one by mistake is genuinely awkward to undo. 404 and 410: the second promises the resource is not coming back.

Choosing codes for your own API

Two mistakes dominate. Returning 200 with an error object in the body defeats every piece of tooling that understands HTTP, from monitoring to retry logic to caches. And using 400 for everything loses the distinction between a malformed request and a well-formed one that failed validation, which is what 422 exists for. Beyond that: 201 with a Location header for creation, 204 for a successful delete, 409 for a conflict, and 429 with Retry-After for rate limiting.

A reference that loads instantly

The whole table ships with the page, so searching is immediate and works offline. Nothing you type is transmitted, stored or logged. To examine the headers that came with a response rather than its status, the HTTP Header Analyzer breaks them down and flags missing security headers.

// HTTP Status Codes: FAQ

What is the difference between 401 and 403?: 401 means authentication is missing or invalid, so supplying valid credentials should fix it. 403 means the server knows who you are and is still refusing, so authenticating again will not help; the account lacks the permission. In practice, if refreshing a token resolves it, it was a 401 situation.
What causes a 502 Bad Gateway?: A proxy or load balancer received an invalid or empty response from the service behind it. Usually that service has crashed, is not running, or returned something unparseable. Check the upstream application first, then the proxy configuration; the client that saw the 502 is almost never the problem.
How is 504 different from 502?: Both come from a gateway, but 502 means the upstream answered badly while 504 means it did not answer in time. A 504 points at latency: a slow query, an overloaded service, or a proxy timeout set lower than the work actually takes.
Should I use 301 or 302 for a redirect?: 301 when the move is permanent and you want search engines and browsers to update. Be careful: browsers cache 301s aggressively and users who have received one may keep following it even after you change your mind. Use 302 or 307 for anything temporary, and 307 or 308 when the HTTP method must be preserved.
When should an API return 422 rather than 400?: 400 for a request the server cannot parse, such as malformed JSON or a missing required parameter. 422 for a request that parsed correctly but failed business validation, such as an email address in the wrong format. The distinction tells the client whether to fix its serialisation or its data.
What does 429 mean and how should I handle it?: You have exceeded a rate limit. The response usually carries Retry-After telling you how long to wait. Respect it, and implement exponential backoff rather than retrying immediately, since a tight retry loop against a rate limiter makes the situation worse for everyone.
Is it acceptable to return 200 with an error in the body?: It is common and it is a mistake. Monitoring, caching, retry logic and client libraries all act on the status code, and reporting success for a failure blinds all of them. Use the status code to say what happened and the body to explain the detail.
What is 418, and is it real?: I am a teapot, defined in RFC 2324 as an April Fools joke in 1998. It is not a real status code, though it appears as an easter egg in a number of servers and frameworks, and there was a minor campaign to keep it when its removal was proposed.
What should I return after a successful DELETE?: 204 No Content is the conventional answer, since there is nothing meaningful to return. 200 with a body is acceptable if you have something useful to say. Returning 404 for deleting something already deleted is a design choice: many APIs return 204 regardless, treating delete as idempotent.
Is anything I search for sent to a server?: No. The whole reference ships with the page, so searching happens in your browser with no request, and it continues to work offline.

// How to Use HTTP Status Codes

Search or filter

Type a code number, or a keyword such as redirect, timeout or permission. Alternatively filter to a class, 4xx for client errors or 5xx for server errors, and browse.
Expand the code

Open an entry to see what the code means, what commonly causes it, and what to do. The causes section is usually the fastest route to the actual problem.
Check the class first when triaging

Remember that 4xx means the request needs fixing and 5xx means the server does. Getting that right before reading logs saves looking in the wrong place.

Category Network