HTTP status codes for application developers

The five classes

The 4xx and 5xx boundary matters to monitoring and retry behavior. A validation failure belongs in 4xx because the caller can change the request. A 5xx response tells operators and clients that the server failed, so using it for invalid input creates false incident signals.

The common application codes

401 vs 403: authentication vs authorization

The historical name of 401 is misleading. In application terms, 401 means the request is not authenticated, while 403 concerns permission after the caller is known.

• 401: no credentials, an expired token or an invalid signature. Supplying valid credentials could change the outcome. The response must include a WWW-Authenticate header, although many APIs omit it.
• 403: the server recognizes the caller but does not allow this action. Retrying with the same identity will not change the result.

400 vs 422

• 400: the server cannot process the request syntax or basic shape, such as malformed JSON, a missing required parameter or an invalid Content-Type.
• 422: the syntax is valid but the values fail semantic validation, such as a malformed email, an end date before the start date or a quantity of −1.

Reasonable APIs draw this line differently. Some use 400 for both parsing and validation errors, then describe the distinction in the body. Either approach can work if it is documented and consistent within the API. Return machine-readable details so clients do not have to parse prose:

{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation failed",
  "status": 422,
  "errors": [
    { "field": "email",   "code": "invalid_format", "message": "Must be a valid email address" },
    { "field": "endDate", "code": "before_start",   "message": "Must be after startDate" }
  ]
}

This follows RFC 9457, Problem Details for HTTP APIs. Adopting that structure gives clients one documented error format instead of a different shape for each endpoint.

Redirects: 301, 302, 307, 308

Browsers historically changed POST to GET when following 301 and 302, even though the original specifications did not define that behavior. The standards later documented the established practice. Codes 307 and 308 provide temporary and permanent redirects while preserving the method and body.

• Moving a page permanently, for SEO: use 301. It is the code search engines treat as a signal to transfer ranking and update the index.
• Redirecting an API POST: use 307 or 308, or the request body will be silently dropped.
• Post/Redirect/Get after a form submission: use 303 See Other. It deliberately converts the follow-up request to GET so refreshing the result does not resubmit the form.

Status-code mistakes that affect clients

Returning 200 with an error in the body

HTTP/1.1 200 OK
{ "success": false, "error": "User not found" }

A 200 response tells client libraries, retry code, monitoring, caches and health checks that the request succeeded. Putting an error only in the body hides the failure from each of those layers. Return the error status on the HTTP status line and use the body for detail.

Using 500 for anything you did not anticipate

Reserve 500 for an unexpected server failure. Invalid input belongs in 4xx. Keeping those categories separate makes dashboards and alerts reflect service incidents instead of routine client mistakes.

Forgetting Retry-After on 429 and 503

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1767229200

Without Retry-After, clients must guess when to try again, and immediate retries can increase load during an already constrained period. The header accepts either a delay in seconds or an HTTP date.

Using 404 for an empty collection

When GET /users?role=admin finds no matches, return 200 with an empty array. The collection exists and the filter produced no members. A 404 suggests that the resource or route itself does not exist.

Which errors are safe to retry

Add jitter to exponential backoff. Without it, clients that failed together also retry together, producing synchronized load while the service is recovering. A random component spreads those attempts over time.

async function withRetry(fn, attempts = 4) {
  for (let i = 0; i < attempts; i++) {
    try {
      return await fn();
    } catch (error) {
      const retryable = [408, 429, 500, 502, 503, 504].includes(error.status);
      if (!retryable || i === attempts - 1) throw error;

      const base = 2 ** i * 250;                  // Retry delays are 250, 500, 1000 ms
      await new Promise(r => setTimeout(r, base + Math.random() * base));
    }
  }
}

502, 503 and 504: which layer failed

• 502 Bad Gateway: the proxy received an invalid response from the application, or no response at all. Check whether the app crashed or is listening on the expected address.
• 503 Service Unavailable: the server is available but cannot currently serve the request, for example during maintenance, load shedding or when no healthy backend remains.
• 504 Gateway Timeout: the upstream application was reachable but did not respond in time. Investigate slow queries and upstream calls as well as configured timeouts.

Use the gateway’s observation to choose the first check. For 502, verify that the process is healthy and returning valid HTTP. For 504, trace where the upstream request spent its time.

Two worth knowing that you rarely see

• 202 Accepted: the server accepted the request but has not finished processing it. For asynchronous work, return 202 with a status URL the client can poll instead of holding the original connection open.
• 412 Precondition Failed: use If-Match with ETag for optimistic concurrency control. The client sends the version it read; if that resource has since changed, the server rejects the update instead of overwriting newer work.