The HTTP Status Codes You Need to Know

Working on the web means coming into contact with HTTP responses. Whether you spend your time primarily on the client or on the server, you're likely familiar with the popular ones like 200, 404, and 500. While memorizing all the codes using cat memes as a mnemonic can be helpful, let's dive deeper into what some of the most common codes mean.

What is an HTTP status code?

HTTP response status codes are a set of standardized and agreed upon numbers that identify information about an http response.

Status codes are 3 digits and broken down into 5 categories, each organized by the first digit of the number. You'll see these abbreviated as the first number, followed by two "x" characters. For example, "4xx".

• 1xx: Informational provides information about a request in progress.
• 2xx: Successful indicates that the request was received and accepted.
• 3xx: Redirection indicates that the request has to be redirected.
• 4xx: Client Error indicates that an error has occurred on the client.
• 5xx: Server Error indicates that an error has occurred on the server.

If you're consuming an API, it is usually safe to assume that it conforms to these standardized codes. If you are the one creating an API, make sure to match your responses with the appropriate code.

The most common response codes

All the x00 codes are fairly common, as they tend to be "catch-alls" used instead of the more specific codes. Here are some of the most popular codes across all categories.

200 (OK)

Everything is great! A status code of 200 is a sign that the request was successful. In most cases, it is safe to check against 200(and anything in the 2xx range) to confirm that no problem occurred.

It is important to keep in mind that a successful request doesn't always mean the same thing from a user perspective. A search query against an API may return 200, even if the response contains no matching results.

301 (Moved Permanently)

While you may not see this too often when making a call to a third-party API, it is useful for configuring servers to handle resources that have moved. For example, restructuring the url of a site from page.site.com to site.com/page can use a 301 to indicate to search engines, the browser, and dependent resources that the page still exists, but it has a new location.

401 (Unauthorized)

The HTTP Authentication specification added the 401 status code. Use it when the request can't be processed because of invalid credentials. While the standard uses the term unauthorized, this technically means authenticated. If you're running into this error code often, make sure to confirm your credentials are correct.

403 (Forbidden)

Not to be confused with 401, the 403 code is for clients that are known to the server, but don't have proper permissions to access a resource. 403 responses may happen when a server or API has a list of approved clients (e.g., domains or IP addresses) that do not match the client making the request.

404 (Not Found)

So popular that non-developers recognize it, 404 is used when the requested resource can't be found. Perhaps it has moved and there is no redirect provided. Maybe the URL provided is simply incorrect. 404 doesn't provide any indication whether this is a temporary or permanent problem. If you are intentionally setting a response to 404, you may be better suited using a more applicable response (one of the redirects, or 410 for "Gone").

408 (Request Timeout)

When a client makes a request to the server and it takes too long, or the server decides to close the connection rather than continue waiting, a 408 status code is sent. Some servers will send this on idle connections, even when the client hasn't sent a request.

429 (Too Many Requests)

Using a third-party API in your application? If you're really using it, you may run into the 429 status code. This happens when you hit the rate-limit by sending too many requests over a period of time. This time-frame and limit will differ depending on the API, but the response will generally include details about the limit and often a Retry-After header with the time you need to wait before making another request.

500 (Internal Server Error)

The 500 status code occurs when the server experienced an unexpected error. This is the default, catch-all, "something went wrong" code to use when there isn't a more appropriate code.

502 (Bad Gateway)

When the server you are connecting to is acting as a gateway or proxy, but receives an invalid request from the server it is trying to reach (origin server). This might happen with standard proxies, or even API Gateways. The gateway itself is working, but the "origin server" that it is trying to reach is having a problem.

503 (Service Unavailable)

The 503 status code means that the server is unavailable temporarily. This may be caused by a resource overload, temporary maintenance, or any situation where the exact issue is unrelated to the request. The expectation with a 503 response is that the service will be available again soon.

504 (Gateway Timeout)

Similar to 502, when the server is a proxy or gateway and hasn't received a response from the "origin server" in an appropriate amount of time it will return a 504 status code. While the root of the problem won't be clear from this response, it means that one of the dependent resource is experiencing a problem that you may want to trace through the gateway.

Expectations and being a good API citizen

These codes are standardized for a reason. As a consumer of APIs, they allow you to make assumptions about a response based on them. As a creator of an API they give you a shorthand to communicate with your user's applications. Take advantage of these codes and the full array of status codes to make developing and consuming APIs more consistent.

Previously published at https://blog.bearer.sh/common-http-status-codes/