HTTP Status Codes

• 200 OK: The request succeeded, and the response usually contains a body.
• 201 Created: The request succeeded and a new resource was created. This is common after a POST request.
• 204 No Content: The request succeeded, but there is no data to return. This is common after a DELETE request.
• 301 / 308 Moved Permanently: The resource has a new permanent URL.
• 304 Not Modified: Your cached copy of the resource is still fresh and can be reused.
• 400 Bad Request: The request was malformed or invalid.
• 401 Unauthorized: You are not authenticated.
• 403 Forbidden: You are authenticated, but you do not have permission to access the resource.
• 404 Not Found: There is no resource at the requested URL.
• 422 Unprocessable Content: The server understood the request, but the data failed validation.
• 429 Too Many Requests: You are being rate limited. Slow down your requests.
• 500 Internal Server Error: The server encountered an unexpected problem.
• 502 / 503: A gateway received a bad response, or the service is temporarily unavailable.

401 versus 403

These two codes are frequently confused, so the difference is worth nailing down. Both refuse the request, but for entirely different reasons.

401 Unauthorized actually means unauthenticated. The server does not know who you are. The fix is to log in or provide valid credentials. Despite the word "unauthorized" in the name, this code is strictly about identity.

403 Forbidden means the server knows exactly who you are and is still saying no. You are logged in, but you do not have permission to view or modify this specific resource. Sending fresh credentials will not help because authentication was never the problem.

A quick test: if logging in would fix the error, it is a 401. If you are already logged in and still blocked, it is a 403.

Choosing codes for your own API

When you build an API endpoint, the status code is part of your contract with the caller. It is worth choosing these codes deliberately. Return 201 when you create something, or 204 when a request succeeds but you have nothing to send back. Use 400 or 422 when the caller provides bad input. Use 401 or 403 for authentication and permission issues. Finally, reserve 5xx codes for situations where your server code actually fails. Picking an honest status code allows clients, caches, and monitoring tools to react correctly without having to parse your response body.

A common pitfall: 200 with an error inside

A tempting mistake is to answer every request with a 200 OK and hide the real outcome inside the response body, like { "error": "not found" }. This causes major problems. Every layer between your server and the caller reads the status code, not your JSON payload. This includes browsers, caches, proxies, and monitoring tools. A 200 tells all of those systems that the request succeeded. As a result, failures get cached, automatic retries fail to trigger, and monitoring dashboards look perfectly healthy while your users experience errors. Always let the status line tell the truth.

Try it now

You can configure curl to print just the status code, which is perfect for seeing how different URLs respond:

That command prints 200. If you point it at a URL that does not exist, like https://example.com/nope, it will return 404. You can also add the -I flag to any curl request to see the full status line and headers together.

What's Next

That completes our look at the HTTP message itself, including its anatomy, methods, headers, and status codes. The next section drops below HTTP to explore the underlying network that carries every one of these messages, starting with IP addresses.