04 / Testing / http-status-codes

HTTP Status Codes

Searchable HTTP status code reference.

ReadyLocal processing
04 · Workspace

How to use

  1. 01Type in the search box to filter by code number, status name or a word from the description, such as rate, cache or timeout.
  2. 02Narrow the list by class with the All, 1xx, 2xx, 3xx, 4xx and 5xx buttons.
  3. 03Read the one-line explanation under each code. Codes are colored by class: green for 1xx and 2xx, amber for 3xx, and red for 4xx and 5xx.
  4. 04Use the list as a quick reference while designing endpoints or reading failed requests.

What is this tool?

A compact, searchable reference covering the 29 HTTP status codes developers and QA engineers meet most often, from 100 Continue to 504 Gateway Timeout. Each code is grouped by class and explained in one line, so you can find the right status without reading the full specification. The data ships with the page, and searching happens in your browser.

401 vs 403, and 400 vs 422

401 Unauthorized actually means unauthenticated. The server does not know who you are, because the credentials are missing, expired or invalid. Sending valid credentials may fix it. 403 Forbidden means the server knows who you are, but that identity is not allowed to do this. Sending the same request again with the same token will not help. In API tests, an expired JWT should produce 401, and a valid token for a user without the right role should produce 403.

400 Bad Request is for requests the server cannot parse, such as malformed JSON, a broken header or invalid framing. 422 Unprocessable Content is for requests that parse fine but fail business validation, such as an end date before a start date or an email field that is not an email. Many APIs use 400 for both, but separating them tells clients whether to fix the syntax or the data.

502 vs 503 vs 504

All three usually come from a proxy, load balancer or gateway rather than your application code. 502 Bad Gateway means the gateway reached the upstream server but got an invalid response or a dropped connection, which often means the app crashed or returned something the proxy could not read. 504 Gateway Timeout means the upstream never answered within the gateway's time limit, so look for slow queries or a hung process. 503 Service Unavailable means the service is temporarily unable to handle requests, for example during maintenance, overload or a failing health check. It is the right code to return on purpose, ideally with a Retry-After header.

A rule of thumb for bug reports: 502 points to the upstream's response, 504 to its speed, and 503 to its availability.

Redirects: 301, 302, 307 and 308

301 and 308 are permanent, so search engines and caches move to the new URL. 302 and 307 are temporary. The difference within each pair is the HTTP method. With 307 and 308, the client must repeat the same method and body, so a POST stays a POST. With 301 and 302, clients historically switch a POST to a GET. Use 308 when you permanently move an API endpoint that receives POST requests, and 301 for ordinary page moves.

304 Not Modified is not a real redirect. It tells the client that its cached copy, validated with an ETag or Last-Modified date, is still valid, so it can reuse that copy.

Common use cases

  • Choosing the correct response code while designing a REST endpoint
  • Writing precise status-code assertions in API test suites
  • Explaining a failure accurately in a bug report or incident note
  • Reviewing OpenAPI contracts for consistent error codes
  • Onboarding new QA engineers to HTTP semantics

FAQ

What is the difference between 401 and 403?

401 means the request is not authenticated because credentials are missing or invalid. 403 means the client is authenticated but does not have permission for this resource.

What is the difference between 502 and 504?

502 Bad Gateway means the upstream server returned an invalid response. 504 Gateway Timeout means the upstream did not respond in time.

When should an API return 422 instead of 400?

Return 422 when the request is well-formed but its content fails validation rules. Return 400 when the request itself is malformed, such as invalid JSON.

What does 429 Too Many Requests mean?

The client has exceeded a rate limit. Well-behaved clients should slow down, and many servers include a Retry-After header saying when to try again.

What is the difference between 404 and 410?

404 means nothing currently matches the URL, with no claim about the future. 410 Gone says the resource was removed on purpose and will not come back.

Are all HTTP status codes listed?

No. The reference covers 29 commonly used codes across the 1xx to 5xx classes. Less common codes such as 303, 412 or 451 are not included.

Does this reference work offline?

Yes. The list ships with the page, and search runs locally in your browser.