Guide

HTTP Status Codes: 401 vs 403, 301 vs 302, 502 vs 504

Short answer: for 401 vs 403 and other confusing pairs, start with the basics: every HTTP response starts with a three-digit code. The first digit is the class: 1xx informational, 2xx success, 3xx redirect, 4xx the client made a mistake, 5xx the server failed. A handful of neighbouring codes are easy to mix up: 401 means "who are you?", 403 means "I know who you are, and no". Look any code up in the searchable HTTP Status Codes list, which has 69 codes with plain-English meanings.

The pairs people mix up

401 vs 403

  • 401 Unauthorized: the request has no valid credentials, so logging in may help. A 401 should come with a WWW-Authenticate header.
  • 403 Forbidden: the server understood who you are and still refuses. Logging in again will not change it.

301 vs 302 vs 307 vs 308

  • 301 and 308 are permanent redirects. 302 and 307 are temporary.
  • Search engines use permanent versus temporary as a hint about which URL to keep, so moving a page for good should be a 301 or 308.
  • 307 and 308 never change the HTTP method. Older clients may turn a POST into a GET after a 301 or 302, which breaks form posts.

400 vs 422

  • 400 Bad Request: the request is malformed.
  • 422 Unprocessable Content: it is well formed but fails validation (an email field with no @).

Many APIs use only 400 for both. Being consistent matters more than being perfect.

500, 502, 503 and 504

  • 500: an error inside the server.
  • 502 Bad Gateway: a gateway or proxy received an invalid answer from the server behind it.
  • 503 Service Unavailable: the service is temporarily overloaded or down.
  • 504 Gateway Timeout: the gateway waited too long for the server behind it.

If you use Cloudflare, codes 520 to 526 are not part of the HTTP standard: Cloudflare uses them to describe problems reaching your origin server.

Choosing a code for an API or a page

Situation Code
Success with a body 200
Something was created 201
Success with no body (after a DELETE) 204
Cached copy is still good (conditional request, e.g. If-None-Match) 304
Record not found 404
Method not allowed (send an Allow header) 405
Rate limited (may send Retry-After) 429

A 429 can carry a Retry-After header saying when to try again. Those headers can be read in the HTTP Header Analyzer; the guide to HTTP response headers and cookie flags explains what the other ones mean.

How to look up 401 vs 403 and other codes with the status code list

  1. Open the HTTP Status Codes page.
  2. Type a number or a word in the search box. The word "redirect" shows 301, 302, 303, 307 and 308.
  3. Use the class filter to narrow to 4xx or 5xx.
  4. To see the real status line of a request, run it with curl -i. The cURL Command Generator builds the command, and the guide to copying a request as cURL shows how to start from the browser's Network tab.
  5. When a redirect sends you to a new address, the URL Parser splits the Location value into its parts.

A note on the teapot

418 I'm a teapot comes from an April Fools' RFC (RFC 2324, 1998). Some APIs use it on purpose, so do not assume it is a mistake when you see it.

Limits to know

  • The list explains the standard meanings. What a particular server means by a code is up to its authors, so check its documentation.
  • The tool does not send requests. To see what a server really returned, read the response yourself.
  • Nothing is uploaded.

Frequently asked questions

What is the difference between 401 and 403? 401 is "not authenticated". 403 is "authenticated, but not allowed".

Should I use 301 or 302? 301 (or 308) for a permanent move, 302 (or 307) for a temporary one.

Which status code should my API return for a missing record? 404 Not Found.

What does 429 mean? Too many requests. The client is being rate limited and may be told when to retry.

Are 520 to 526 standard HTTP codes? No. They are Cloudflare-specific.

Related tools and guides

Sources and further reading