HTTP Status Codes: Complete Reference for Developers

HTTP status codes are the first thing you check when something goes wrong with an API call. They tell you whether the request succeeded, whether the server understood what you wanted, and if it failed, roughly why it failed.

Most developers know the big ones: 200 means success, 404 means not found, 500 means the server broke. But there are dozens of status codes across five categories, and knowing the difference between a 401 and a 403, or a 301 and a 302, can save you hours of debugging.

This guide covers every status code you are likely to encounter in real-world web development, organized by category with practical notes on when each one applies.

1xx Informational: Rarely Seen, Good to Know

The 100-series codes are informational. They tell the client that the server has received the request and is continuing to process it. You will almost never see these in application code, but they exist in the HTTP spec.

100 Continue: The server received the request headers and the client should proceed to send the body. This shows up in large file uploads where the client sends an Expect: 100-continue header to check if the server will accept the upload before sending the full payload.

101 Switching Protocols: The server agrees to switch to a different protocol. This is how WebSocket connections start. The client sends an HTTP upgrade request, the server responds with 101, and the connection switches from HTTP to WebSocket.

102 Processing: Used with WebDAV to indicate that the server received the request and is processing it, but no response is available yet. Rare outside of WebDAV applications.

103 Early Hints: A relatively new code that lets the server send preliminary headers (like preload hints for CSS or JavaScript) before the final response. This helps browsers start loading critical resources earlier.

2xx Success: The Happy Path

These are the codes you want to see. They mean the request was received, understood, and processed successfully.

200 OK: The standard success response. For GET requests, the response body contains the requested resource. For POST requests, the body contains the result of the action.

201 Created: The request succeeded and a new resource was created. Typically returned after a POST request that creates a new database record, user account, or file. The Location header usually contains the URL of the new resource.

204 No Content: Success, but there is nothing to send back. Common response for DELETE requests (the resource was deleted, there is nothing to return) and PUT requests where you do not need to see the updated resource.

206 Partial Content: The server is delivering only part of the resource. Used with range requests for large file downloads, video streaming, and resumable uploads. The Content-Range header tells the client which bytes are included.

For API development, the most common mistake is returning 200 for everything. Use 201 when creating resources and 204 when deleting them. It makes your API more predictable for consumers. Test your status codes with the API Request Builder to verify that each endpoint returns the correct code for each scenario.

3xx Redirection: Moved, Temporarily or Permanently

Redirect codes tell the client to look somewhere else for the resource.

301 Moved Permanently: The resource has moved to a new URL forever. Search engines transfer the SEO value from the old URL to the new one. Use this for domain changes, URL restructuring, and removing trailing slashes. Browsers cache 301 redirects aggressively, so be certain before deploying one.

302 Found (Temporary Redirect): The resource is temporarily at a different URL, but the original URL should still be used for future requests. Use this for maintenance pages, A/B tests, and temporary content moves. Search engines do not transfer SEO value because the redirect is temporary.

304 Not Modified: This is not really a redirect. It tells the client that the cached version of the resource is still valid. The server checks the If-Modified-Since or If-None-Match headers and responds with 304 if nothing changed, saving bandwidth by not resending the full response body.

307 Temporary Redirect: Like 302, but guarantees that the HTTP method (GET, POST, etc.) is preserved in the redirect. A POST request redirected with 307 will remain a POST at the new URL. With 302, some browsers convert POST to GET, which can break form submissions.

308 Permanent Redirect: Like 301, but preserves the HTTP method. The permanent equivalent of 307.

The difference between 301/302 and 308/307 is subtle but matters for API development. Use the JSON Formatter to inspect redirect responses and verify the headers are set correctly.

4xx Client Errors: Your Request Has a Problem

These codes mean the request was invalid in some way, and the client needs to fix something before trying again.

400 Bad Request: The request is malformed. Missing required fields, invalid JSON, wrong data types, or values outside acceptable ranges. Your API should include a descriptive error message in the response body explaining exactly what is wrong.

401 Unauthorized: The request lacks valid authentication credentials. The user is not logged in, the token has expired, or the API key is missing. The correct response to a 401 is to authenticate (log in, refresh the token) and retry.

403 Forbidden: Authentication succeeded, but the user does not have permission to access this resource. The difference from 401: with 401, logging in might fix the problem. With 403, logging in will not help because the user simply does not have access. A regular user trying to access an admin endpoint gets 403.

404 Not Found: The resource does not exist at this URL. Either the URL is wrong, or the resource was deleted. This is the most familiar error code on the web.

405 Method Not Allowed: The URL exists but does not support the HTTP method you used. Sending a DELETE request to an endpoint that only accepts GET and POST returns 405.

409 Conflict: The request conflicts with the current state of the resource. Common in APIs when trying to create a resource that already exists, or when updating a resource that was modified by another request since you last read it (optimistic concurrency).

422 Unprocessable Entity: The request is well-formed (valid JSON, correct content type) but the data does not pass validation rules. Username too short, email already taken, date in the past. This is more specific than 400 and is becoming the standard for validation errors in REST APIs.

429 Too Many Requests: Rate limit exceeded. The response usually includes a Retry-After header telling the client how long to wait before trying again.

5xx Server Errors: Something Broke on the Backend

These codes mean the server failed to fulfill a valid request. The problem is on the server side, not the client side.

500 Internal Server Error: The generic catch-all for server failures. An unhandled exception, a null pointer, a failed database query, or any other unexpected error on the server. If your API returns 500 frequently, your error handling needs work. Every anticipated failure should return a specific 4xx code with a helpful message.

502 Bad Gateway: The server acting as a proxy or gateway received an invalid response from the upstream server. Common with reverse proxies like Nginx when the application server behind it crashes or is unreachable.

503 Service Unavailable: The server is temporarily unable to handle the request. Usually because it is overloaded, undergoing maintenance, or starting up. The Retry-After header tells the client when to try again.

504 Gateway Timeout: Like 502, but specifically a timeout. The proxy waited too long for the upstream server to respond. If your API calls take too long (heavy database queries, slow external API calls), the proxy will return 504 before your code finishes executing.

When debugging 5xx errors, the status code alone is not enough. Check the server logs, the response body (if any), and the request that triggered the error. Use the URL Encoder to ensure your request URLs are properly encoded, since malformed URLs sometimes trigger 500 errors that look like server problems but are actually client issues.

Choosing the Right Status Code for Your API

When building APIs, consistency matters more than perfection. Pick a convention and stick to it across all your endpoints.

A reasonable default convention for REST APIs:

• GET success: 200 with the resource in the body
• POST creating a resource: 201 with the new resource in the body and a Location header
• PUT/PATCH update: 200 with the updated resource, or 204 if you do not return the body
• DELETE: 204 with no body
• Validation failure: 422 with error details in the body
• Authentication required: 401
• Authorization denied: 403
• Resource not found: 404
• Rate limited: 429 with Retry-After header
• Server error: 500 with a generic error message (never expose stack traces to clients)

Document your status codes in your API specification. Consumers of your API should never have to guess what a particular code means in context. If you use non-standard codes (some APIs use 418, 451, or custom codes), explain them clearly.

FAQ

What is the difference between 401 and 403?

401 means the server does not know who you are (unauthenticated). 403 means the server knows who you are but you do not have permission (unauthorized). If logging in would fix the problem, use 401. If the user is already logged in but lacks the required role or permissions, use 403.

Should I use 404 or 410 for deleted resources?

404 means the resource was not found (it might never have existed). 410 Gone means the resource existed but has been intentionally deleted and will not come back. Use 410 when you want search engines to remove the URL from their index faster. For most APIs, 404 is sufficient.

Why does my server return 502 instead of the actual error?

A 502 means your reverse proxy (Nginx, Cloudflare, or your hosting provider) cannot reach your application server. The application server has either crashed, run out of memory, or is not listening on the expected port. Check your application logs and server process status.

Is it okay to use non-standard status codes like 418?

418 (I'm a Teapot) was an April Fools joke in the HTTP spec and should not be used in production. Custom status codes in the 4xx or 5xx range are technically allowed but confuse API consumers. Stick to the standard codes and use the response body for additional context.