New in 2.4: Test runs you can trust See what's new →

HTTP status codes list, with a live endpoint to test each one

Share

Lists of HTTP status codes are easy to find. MDN and the IANA registry have every code and what it means. What they can't do is send you a 503 so you can watch what your code does with it. This list has the same codes, a short note on what each means in an API, and a live URL that returns it: https://api.testingapis.com/api/status/{code}. No key and no sign-up.

Use it to check that your HTTP client, retry logic or error screen behaves the way you think it does, before a real server finds out for you.

Request any status code

Put the code in the path. The response has that status, a small JSON body and the headers the status normally carries:

Terminal
$ curl -i https://api.testingapis.com/api/status/404
HTTP/1.1 404 Not Found
content-type: application/json; charset=utf-8

{"status":404,"statusText":"Not Found","category":"client-error",
 "message":"This is a 404 response. Use /api/status/{code} to request any status."}

$ curl -i https://api.testingapis.com/api/status/401
HTTP/1.1 401 Unauthorized
content-type: application/json; charset=utf-8
www-authenticate: Basic realm="TestingAPIs"

{"status":401,"statusText":"Unauthorized","category":"client-error", ...}

Any method works (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS), and CORS is open, so you can call it from a page on localhost too. These are the headers that come with particular codes:

Terminal
$ curl -s -D - -o /dev/null https://api.testingapis.com/api/status/405 | grep -i allow
allow: GET, POST

$ curl -s -D - -o /dev/null https://api.testingapis.com/api/status/429 | grep -i retry
retry-after: 5

$ curl -s -D - -o /dev/null https://api.testingapis.com/api/status/301 | grep -i location
location: /api/echo

$ curl -s -D - -o /dev/null https://api.testingapis.com/api/status/416 | grep -i content-range
content-range: bytes */0

Every 3xx except 304 points Location at /api/echo, so a client that follows the redirect lands on an endpoint that shows the request it sent. 401 adds WWW-Authenticate, 407 adds Proxy-Authenticate, and 204, 205 and 304 have no body.

The full list

The same list is available as JSON, if you want to loop over it in a test:

Terminal
$ curl -s https://api.testingapis.com/api/status/list
[{"code":100,"statusText":"Continue","category":"informational","supported":false,"url":null},
 {"code":200,"statusText":"OK","category":"success","supported":true,"url":"/api/status/200"},
 ...63 entries in all]

Codes marked non-standardaren't in the IANA registry, but you will meet them in the wild. Names follow RFC 9110 where it renamed a code.

1xx Informational

These are interim responses, sent before the final one, so a server can't answer with them alone and the endpoint returns 400 for them:

Terminal
$ curl -s https://api.testingapis.com/api/status/100
{"status":400,"error":"Bad Request",
 "message":"Status code must be between 200 and 599 (1xx cannot be sent as a final response)."}
CodeNameWhat it means
100ContinueThe server accepts the headers; send the body. Follows Expect: 100-continue.
101Switching ProtocolsThe connection changes protocol, as in a WebSocket upgrade.
102ProcessingWebDAV: still working. Deprecated.

2xx Success

CodeNameWhat it means in an API
200OKThe request worked and the body has the result.
201CreatedA POST created something. Usually with a Location header for the new resource.
202AcceptedThe work is queued, not done. Poll a status URL. See the jobs API.
203Non-Authoritative InformationA proxy changed the origin's response.
204No ContentSuccess with no body. Common after DELETE or PUT. Don't parse it as JSON.
205Reset ContentSuccess; the client should clear the form it sent. Rare in APIs.
206Partial ContentThe body is the byte range asked for with a Range header.
207Multi-StatusWebDAV: the body holds a status for each of several resources.
208Already ReportedWebDAV: the member was listed earlier in the same response.
226IM UsedDelta encoding. Almost never seen.

3xx Redirection

CodeNameWhat it means in an API
300Multiple ChoicesSeveral representations exist. Rarely used.
301Moved PermanentlyUse the new URL from now on. Clients may turn a POST into a GET.
302FoundTemporary move. Clients may turn a POST into a GET too.
303See OtherGo GET the result elsewhere. The usual answer after a POST that starts a job.
304Not ModifiedYour cached copy is still good. Answer to If-None-Match or If-Modified-Since. No body.
305Use ProxyDeprecated. Clients ignore it.
306(Unused)Reserved. The JSON list calls it "Switch Proxy", its old name.
307Temporary RedirectTemporary move that keeps the method and body.
308Permanent RedirectPermanent move that keeps the method and body.

4xx Client errors

CodeNameWhat it means in an API
400Bad RequestThe request is malformed: bad JSON, a wrong type, a missing parameter.
401UnauthorizedNo credentials, or bad ones. Send WWW-Authenticate. Retry after logging in.
402Payment RequiredReserved. Some APIs use it for an unpaid plan or exhausted credits.
403ForbiddenThe server knows who you are, and the answer is still no.
404Not FoundNo resource at this URL. Also used to hide resources you may not see.
405Method Not AllowedThe URL exists, the method doesn't. Allow lists the ones that work.
406Not AcceptableThe server can't produce any format your Accept header asks for.
407Proxy Authentication RequiredLike 401, but the proxy wants the credentials.
408Request TimeoutThe client took too long to send the request.
409ConflictThe request clashes with the current state: a duplicate, or an edit on a stale version.
410GoneIt existed and was removed on purpose. Don't retry.
411Length RequiredThe server wants a Content-Length header.
412Precondition FailedAn If-Match or similar condition was false. Someone else changed it first.
413Content Too LargeThe body is over the server's limit. Called Payload Too Large before RFC 9110.
414URI Too LongUsually too much data in the query string. Move it to a body.
415Unsupported Media TypeThe server can't read the body's Content-Type. Often a missing JSON header.
416Range Not SatisfiableThe Range asked for is outside the file.
417Expectation FailedThe server can't meet the Expect header.
418I'm a teapotAn April Fools' joke from RFC 2324. Reserved, so nobody can reuse the number.
419Authentication TimeoutNon-standard. Laravel sends it when a CSRF token has expired.
421Misdirected RequestThe request reached a server that can't answer for this host.
422Unprocessable ContentValid JSON, invalid values. The usual code for validation errors.
423LockedWebDAV: the resource is locked.
424Failed DependencyWebDAV: failed because an earlier request failed.
426Upgrade RequiredSwitch to another protocol, such as a newer TLS or HTTP version.
428Precondition RequiredThe server wants a conditional request, such as one with If-Match.
429Too Many RequestsRate limited. Wait for Retry-After before trying again.
431Request Header Fields Too LargeHeaders too big, often from too many cookies.
451Unavailable For Legal ReasonsBlocked for legal reasons, such as a court order.
499Client Closed RequestNon-standard, from nginx: the client hung up before the answer.

5xx Server errors

CodeNameWhat it means in an API
500Internal Server ErrorAn unhandled bug on the server. Retrying rarely helps.
501Not ImplementedThe server doesn't support the method or feature at all.
502Bad GatewayA proxy or gateway got a bad answer from the server behind it.
503Service UnavailableOverloaded or down for maintenance. Often has Retry-After. Safe to retry.
504Gateway TimeoutThe server behind the proxy didn't answer in time.
505HTTP Version Not SupportedThe server doesn't speak that HTTP version.
506Variant Also NegotiatesA content negotiation misconfiguration. Very rare.
507Insufficient StorageWebDAV: the server is out of space.
508Loop DetectedWebDAV: an infinite loop while processing.
510Not ExtendedObsolete. You won't need it.
511Network Authentication RequiredA captive portal, such as hotel Wi-Fi, wants you to log in.

The endpoint also accepts codes that aren't in any list, such as 599, as long as they are between 200 and 599. That's useful for checking what your client does with a code it has never seen. It should treat it like the generic code for its class, so 599 like 500.

What your client does with each code

Knowing what a code means is half of it. The other half is what your HTTP library does when it gets one, and that is where most bugs are.

JavaScript fetch

fetch only rejects on network errors. A 404 or a 500 is a normal response with ok set to false. Redirects are followed by default, and an empty 204 body breaks res.json(). These results come from Node 24:

JavaScript
const STATUS = "https://api.testingapis.com/api/status";

let res = await fetch(`${STATUS}/404`);
console.log(res.ok, res.status);          // false 404  (no exception)

res = await fetch(`${STATUS}/301`);
console.log(res.status, res.redirected);  // 200 true   (followed to /api/echo)

res = await fetch(`${STATUS}/301`, { redirect: "manual" });
console.log(res.status, res.headers.get("location")); // 301 /api/echo  (in Node)

res = await fetch(`${STATUS}/204`);
await res.json();  // SyntaxError: Unexpected end of JSON input

In a browser, redirect: "manual"gives you an opaque response with status 0 and no headers, so you can't read Location there.

Python requests

requests doesn't raise on error codes either until you call raise_for_status(), and it follows redirects for every method except HEAD:

Python
import requests

STATUS = "https://api.testingapis.com/api/status"

r = requests.get(f"{STATUS}/503", timeout=10)
print(r.status_code, r.reason, r.headers["Retry-After"])
# 503 Service Unavailable 5
r.raise_for_status()
# requests.exceptions.HTTPError: 503 Server Error: Service Unavailable for url: ...

r = requests.get(f"{STATUS}/302", timeout=10)
print(r.status_code, r.history, r.url)
# 200 [<Response [302]>] https://api.testingapis.com/api/echo

r = requests.get(f"{STATUS}/302", allow_redirects=False, timeout=10)
print(r.status_code, r.headers["Location"])
# 302 /api/echo

Redirects can change your method

This one surprises people. After a 301 or 302, browsers and most clients send the next request as a GET and drop the body. 307 and 308 exist to stop that. Since the redirect target here is an echo endpoint, you can see it happen:

Terminal
# 302 and 301: curl -L (like browsers) resends a POST as a GET.
$ curl -s -L -d 'a=1' https://api.testingapis.com/api/status/302 | head -c 40
{"method":"GET","url":"https://api.test

# 307 and 308 keep the method and the body.
$ curl -s -L -X POST -H 'Content-Type: application/json' -d '{"a":1}' \
    https://api.testingapis.com/api/status/307 | head -c 40
{"method":"POST","url":"https://api.tes

If your API moves a POST endpoint, redirect with 308, not 301.

A test suite for your error handling

Here is a small fetch wrapper that turns error codes into exceptions and handles 204, and a node:test suite that runs it against real status codes. Swap in your own wrapper and keep the tests.

api-client.js
export class HttpError extends Error {
  constructor(status, body, retryAfter) {
    super(`HTTP ${status}`);
    this.status = status;
    this.body = body;
    this.retryAfter = retryAfter;
  }
}

export async function getJson(url) {
  const res = await fetch(url);
  if (res.status === 204) return null;
  const text = await res.text();
  const body = text ? JSON.parse(text) : null;
  if (!res.ok) {
    const retryAfter = Number(res.headers.get("Retry-After")) || null;
    throw new HttpError(res.status, body, retryAfter);
  }
  return body;
}
status.test.js
import { test } from "node:test";
import assert from "node:assert/strict";
import { getJson, HttpError } from "./api-client.js";

const STATUS = "https://api.testingapis.com/api/status";

test("200 returns the parsed body", async () => {
  const body = await getJson(`${STATUS}/200`);
  assert.equal(body.status, 200);
});

test("204 returns null instead of failing to parse", async () => {
  assert.equal(await getJson(`${STATUS}/204`), null);
});

for (const code of [400, 401, 403, 404, 409, 422, 500, 502]) {
  test(`${code} throws an HttpError with the status`, async () => {
    await assert.rejects(getJson(`${STATUS}/${code}`), (err) => {
      assert.ok(err instanceof HttpError);
      assert.equal(err.status, code);
      return true;
    });
  });
}

for (const code of [429, 503]) {
  test(`${code} keeps Retry-After for the caller`, async () => {
    await assert.rejects(getJson(`${STATUS}/${code}`), (err) => {
      assert.equal(err.retryAfter, 5);
      return true;
    });
  });
}
Text
$ node --test status.test.js
✔ 200 returns the parsed body
✔ 204 returns null instead of failing to parse
✔ 400 throws an HttpError with the status
...
✔ 503 keeps Retry-After for the caller
ℹ tests 12
ℹ pass 12
ℹ fail 0

The suite needs no mock server and no stubbed fetch, so it tests the code that really runs. If you want an error inside a real-looking resource instead, most of the data APIs take an ?error= parameter, which the guide to mock API error responses covers.

Flaky responses for retry tests

Retry logic needs an endpoint that sometimes fails. /api/status/random picks a code from a weighted pool each time. 200:3,503:1 makes 200 three times as likely as 503:

Terminal
$ for i in 1 2 3 4 5 6; do curl -s -o /dev/null -w "%{http_code} " \
    "https://api.testingapis.com/api/status/random?codes=200:3,503:1"; done
200 200 200 503 200 200

The X-Status-Pool response header shows the pool it parsed. Up to 20 codes are allowed, weights 1 to 100. For timeouts, dropped connections and slow responses, use the chaos endpoints. The 503 handling guide shows a full retry test in C#.

Common mistakes

MistakeWhat happensFix
Assuming fetch throws on 404 or 500The error body gets rendered as if it were dataCheck res.ok or res.status before parsing
Calling res.json() on every response204 and 304 throw a SyntaxErrorReturn early on 204, or read text() first
Asserting on statusTextHTTP/2 has no reason phrase, so it's often empty. Here, 418 comes back as "Unknown"Assert on the number only
Retrying every errorA 400 or 422 fails again, and a non-idempotent POST may run twiceRetry 408, 429, 502, 503 and 504; respect Retry-After
Treating 401 and 403 the sameUsers get logged out when they only lack a permission401: log in again. 403: show that access is denied
Moving a POST endpoint with 301Clients follow it as a GET and lose the bodyUse 308
Returning 200 with an error in the bodyClients, caches and monitoring all think it workedSend the real status code

Questions

How many HTTP status codes are there?

The IANA registry lists a little over 60 codes in use, and the five classes leave room for 500. The list endpoint here has 63, including three non-standard ones (419, 499 and the old name for 306). In practice most APIs use around fifteen: 200, 201, 204, 301, 304, 400, 401, 403, 404, 409, 422, 429, 500, 502 and 503.

Should a validation error be 400 or 422?

Both are common. A frequent split is 400 when the request can't be parsed and 422 when it parses but the values break a rule. The lesson on validation errors shows how to test either.

Can I get a 1xx response from the endpoint?

No. A 1xx is never a final response, so the endpoint returns 400 for codes below 200. They appear in the JSON list with supported: false.

Is there a quick way to look a code up?

The HTTP status code tool searches every code by number or name. For how responses fit together (status line, headers, body), see the lesson on HTTP responses.

The Status API reference has all three endpoints, with a form to send each request from the browser.