Pointer Walk

HTTP Status Codes

The nine codes you will debug, sorted by whose fault it is: yours, theirs, or the network in between.

NetworkingBeginner8 min read

Three digits that tell you where to look

Every HTTP response begins with a three-digit status code. Before you read a single line of the body, it tells you how the request went, and, when something failed, whose problem it is.

The first digit gives the family:

RangeMeaningIn short
2xxSuccessIt worked
3xxRedirectionLook somewhere else
4xxClient errorYou sent something wrong
5xxServer errorThey failed, though your request was fine

Most of the time you see 200 OK and think nothing of it. This page is about the nine you will meet when things go wrong, sorted by who has to fix it.

404 Not Found · whose problem: yoursInteractive
Status
Your code
Gateway
Server

Pick a code and step through the exchange that produces it.

Your side: the 4xx codes

A 4xx means the server looked at your request and declined it. Sending the same request again will give the same answer. Change something first.

400 Bad Request

The request could not be understood: malformed JSON, a missing required field, a value of the wrong type. Read the response body. A good API says exactly what was wrong.

401 Unauthorized

"I do not know who you are." No credentials were sent, or they are invalid or expired. The name is misleading: it is about identity, not permission.

Fix: log in, or refresh the token, and send it again.

403 Forbidden

"I know who you are, and the answer is no." You are identified, and you do not have permission.

Fix: logging in again will not help. You need a different role, or you are asking for something you should not.

Example

401 or 403?

You try to open the staff door of a shop.

401: "Who are you? Show me a badge."

403: "I can see your badge. Customers are not allowed back here."

404 Not Found

Nothing lives at that address. A typo in the path, an id that does not exist, or a record that was deleted. Some servers return 404 in place of 403 on purpose, so as not to reveal that a hidden thing exists.

429 Too Many Requests

Each request was fine. There were just too many. A rate limiter turned you away.

Fix: slow down. Look for a Retry-After header saying how long to wait. See Rate Limiting.

Their side: the 5xx codes from the server

A 5xx means your request was acceptable and the failure happened on the other end.

500 Internal Server Error

The catch-all for "something broke in our code": an unhandled exception, a bug, a failed query. The response usually says little, for safety. The real explanation is in the server's logs.

If it is your server, that is where to look. If it is someone else's, there is nothing to fix on your side.

503 Service Unavailable

"Not right now." The server is overloaded, restarting or down for maintenance. Unlike a 500, this is explicitly temporary.

Fix: retry after a pause, and make the pause longer each time. See Retries, Backoff and Jitter.

In between: the gateway codes

Your request seldom goes straight to the application. It passes through a gateway: a load balancer, reverse proxy or CDN that forwards it to a server behind. Two codes are produced by that middle layer, about the server behind it.

502 Bad Gateway

The gateway forwarded your request and got back something unusable: a refused connection, a reset, or a garbled reply. Usually the application behind it has crashed or is not running.

504 Gateway Timeout

The gateway forwarded your request and waited. The server did not answer within the gateway's time limit. Usually the application is alive but too slow: a long query, or it is itself waiting on something.

Example

502 or 504?

You ask a receptionist to fetch someone from the back office.

502: "I knocked. Nobody is in there."

504: "They said 'one moment' twenty minutes ago and I have given up waiting."

In both cases the gateway is fine and so is your request. Look at the service behind the gateway.

All nine, by who fixes it

CodeNameWho fixes itRetry the same request?
400Bad RequestYouNo: fix the request
401UnauthorizedYouAfter logging in
403ForbiddenYouNo: you lack permission
404Not FoundYouNo: check the address
429Too Many RequestsYouYes, after waiting
500Internal Server ErrorThe server's ownerRarely helps
503Service UnavailableThe server's ownerYes, after a pause
502Bad GatewayWhoever runs the service behind the gatewayMaybe, after a pause
504Gateway TimeoutWhoever runs the service behind the gatewayCareful: the first attempt may still be running

Key takeaways

  • The first digit says who is responsible: 4xx is the client, 5xx is the server.
  • 401 means you are not identified. 403 means you are identified and not allowed.
  • 429 means slow down. 503 means try again later. Both are worth retrying after a wait.
  • 500 is a failure inside the server, and the details are in its logs.
  • 502 and 504 come from a gateway reporting on the server behind it: no usable answer, or no answer in time.

Your progress

Check your progress

0%

  1. Read the page50% of this page

    When you have gone through the page and its animations, tick it off.

  2. Take the quiz50% of this page

    7 questions, from easy to hard. Take it as often as you like: the questions change, and only your best score counts.

Saved on this device only. See all your progress