Understanding HTTP Status Codes: A Developer's Quick Reference

Every HTTP response carries a three-digit status code that tells the client what happened with the request. This code is the first thing your browser, your API client, and your application code check when processing a response. Understanding what each code means — and what to do when you encounter an unexpected one — is fundamental to building and debugging web applications.

Status codes are grouped into five ranges. 1xx codes provide informational context. 2xx codes indicate success. 3xx codes handle redirection. 4xx codes indicate client errors — the request was malformed or unauthorized. 5xx codes indicate server errors — something went wrong on the server side while processing a valid request.

This grouping matters for error handling logic. A 4xx error means the client needs to change something — fix the request body, provide authentication, or use the correct URL. Retrying the same request without changes will produce the same error. A 5xx error means the server had a problem — the request might be fine, and retrying after a delay could succeed. Your error handling code should distinguish between these categories.

Status codes also matter for monitoring and observability. A sudden spike in 500 responses indicates a production issue. A gradual increase in 404 responses might indicate broken links or a routing misconfiguration. A high rate of 401 responses could signal an authentication service problem. Tracking status code distributions gives you a real-time health signal that complements your application-level metrics.

The HTTP specification defines over 60 status codes, but in practice, most developers encounter fewer than 20 regularly. This guide focuses on the codes you will see most often, explains what they mean in practical terms, and describes how to handle them in your applications.

200 OK is the standard success response. The server processed the request successfully and is returning the requested data. For GET requests, the response body contains the resource. For POST requests, the body typically contains the created resource or a confirmation. This is the response you expect for most successful operations.

201 Created indicates that a POST request successfully created a new resource. The response should include a Location header pointing to the URL of the newly created resource. Use 201 instead of 200 when your API endpoint creates a new entity — it communicates the result more precisely and allows clients to find the new resource without parsing the response body.

204 No Content indicates success but returns no response body. This is the correct response for DELETE requests that succeed, PUT or PATCH requests that update a resource without returning the updated representation, and any operation where the client already has all the information it needs. Returning 204 instead of 200 with an empty body saves bandwidth and signals to the client that there is no body to parse.

202 Accepted indicates that the request has been accepted for processing but the processing has not been completed. This is common for long-running operations: sending emails, generating reports, processing video, or any asynchronous task. The response body typically includes a status URL that the client can poll to check progress.

206 Partial Content is returned when the server fulfills a range request — delivering only part of a resource. This is most commonly seen with large file downloads and video streaming, where the client requests specific byte ranges. If your application serves large files, supporting range requests with 206 responses enables resumable downloads and efficient streaming.

301 Moved Permanently tells the client that the requested resource has been permanently moved to a new URL provided in the Location header. Browsers cache 301 redirects aggressively, which is great for permanent URL changes but dangerous if you use 301 for temporary redirects — the browser will remember the redirect even after you remove it. Use 301 when you are absolutely certain the old URL will never serve content again.

302 Found is the most misunderstood status code. Technically it means "the resource is temporarily at a different URL," but historically browsers treated it like 303. In modern usage, prefer 303 See Other (for redirecting after a POST) or 307 Temporary Redirect (for preserving the request method). Reserve 302 for backward compatibility with older clients.

304 Not Modified is a caching optimization. When a client sends a conditional request with an If-None-Match (ETag) or If-Modified-Since header, and the resource has not changed, the server returns 304 with no body. The client uses its cached copy. This saves bandwidth and server load for unchanged resources — it is one of the most important performance optimizations on the web.

307 Temporary Redirect preserves the HTTP method of the original request, unlike 302 which some clients convert to GET. If a POST request gets a 307, the redirected request is also a POST. This makes 307 the correct choice for temporary redirects where the method must be preserved, such as redirecting an API endpoint during maintenance.

308 Permanent Redirect is the method-preserving equivalent of 301. Like 307, it guarantees that the HTTP method does not change during the redirect. Use 308 when you are permanently moving an endpoint and need to ensure POST requests stay as POST requests.

400 Bad Request is the generic client error. The server cannot process the request because it is malformed, contains invalid parameters, or violates the API's contract. Common causes include malformed JSON in the request body, missing required fields, values outside acceptable ranges, and syntactically invalid query parameters. When returning 400, include a descriptive error message that tells the client exactly what is wrong.

401 Unauthorized means the request requires authentication and the client has not provided it or has provided invalid credentials. The response should include a WWW-Authenticate header describing the authentication method. Note that 401 means "not authenticated," not "not authorized" — the naming is a historical artifact. If the user is authenticated but lacks permission, use 403 instead.

403 Forbidden means the server understands the request and the client is authenticated, but the client does not have permission to perform the requested action. Unlike 401, re-authenticating will not help — the account itself lacks the necessary role or permission. Common scenarios include accessing another user's private data, modifying a read-only resource, or performing an admin action with a regular user account.

404 Not Found means the requested resource does not exist at the specified URL. This can mean the URL is wrong, the resource was deleted, or the resource exists but the authenticated user cannot see it (some APIs return 404 instead of 403 to avoid confirming a resource's existence). In APIs, returning a helpful error body with documentation links or suggestions reduces developer frustration.

429 Too Many Requests is returned when the client has exceeded a rate limit. The response should include headers indicating when the client can retry (Retry-After or X-RateLimit-Reset). Handling 429 correctly — implementing exponential backoff, respecting rate limit headers, and queuing requests — is essential for API clients that run in production.

500 Internal Server Error is the catch-all server error. Something went wrong on the server, and it could not fulfill the request. This is the error you see most often in production incidents — an unhandled exception, a null reference, a timeout connecting to a database, or any other unexpected server-side failure. When you see a 500, the server logs contain the actual error details.

502 Bad Gateway means your server received an invalid response from an upstream server. In modern architectures with reverse proxies, load balancers, and API gateways, 502 typically means the upstream application server is down, unreachable, or returning malformed responses. If you see 502 errors, check whether your application servers are running and healthy.

503 Service Unavailable means the server is temporarily unable to handle the request, usually due to maintenance or overload. Unlike 500, which indicates a bug, 503 indicates a transient condition — the service is expected to recover. If your application has a maintenance mode, it should return 503. If your server is overwhelmed by traffic, returning 503 with a Retry-After header is better than accepting requests that will timeout or fail.

504 Gateway Timeout means the gateway or proxy did not receive a timely response from the upstream server. This typically indicates that your application is taking too long to process a request — a slow database query, a blocked thread, or an external API call that is not timing out fast enough. Addressing 504 errors usually involves optimizing the slow operation, increasing timeout thresholds on the proxy, or adding caching.

When handling 5xx errors in client code, the key distinction from 4xx errors is that retrying might work. Implement exponential backoff with jitter for 500, 502, 503, and 504 errors. Start with a short delay (1 second), double it on each retry, cap it at a maximum (30 seconds), and add random jitter to prevent all clients from retrying simultaneously. After 3-5 retries, give up and surface the error to the user.

When debugging an API issue, the status code is your first diagnostic signal. Here is a practical decision framework for common scenarios.

You get a 400. The request is malformed. Open the API Request Builder and reconstruct the request carefully. Check the JSON body for syntax errors using the JSON Formatter. Verify that all required fields are present and that values match the API's expected types. Compare your request against the API documentation. Most 400 errors are caused by typos, missing fields, or incorrect data types.

You get a 401. Authentication is missing or invalid. Check that you are sending the correct authorization header — Bearer token, API key, or basic auth. If using a JWT, decode it with the JWT Decoder to verify the claims are correct and the token has not expired. Check that you are using the right credentials for the environment (test vs. production keys are a common source of confusion).

You get a 403. You are authenticated but not authorized. Verify that your account has the necessary permissions or role. Check whether the resource belongs to a different organization or project. Some APIs return 403 when a free-tier account tries to access a premium endpoint — check your subscription level.

You get a 404. First, check the URL carefully — a typo in the endpoint path is the most common cause. If the URL is correct, the resource may have been deleted or the ID may be wrong. For REST APIs, verify that the resource ID in the URL path corresponds to an existing record.

You get a 500 or 502 or 503. The server is having trouble. Check the service status page if one exists. Try the request again after a minute — transient errors are common. If the error persists, the issue is on the server side and you may need to contact the API provider or check your own server logs if you control the backend.

For constructing and testing API requests during debugging, the API Request Builder provides a structured interface that eliminates manual cURL syntax errors, the JSON Formatter helps inspect request and response bodies, and the cURL to Code converter translates working cURL commands into your preferred programming language for integration into your application.