HTTP Status Codes: A Senior Developer's Decision Tree for Returning the Right Response

In production API reviews, I repeatedly see teams spend weeks discussing architecture, authentication, caching, and deployment pipelines — then return 200 OK with a JSON error body for half their failure states. Wrong HTTP status codes do not just make APIs untidy. They break retries, confuse frontend state handling, hide operational failures from monitoring, and force every consuming client to guess what actually happened.

I have reviewed hundreds of API implementations over fifteen years. The status code handling is almost always the most visible sign of an engineer's production experience. Junior developers return 200 for everything and put "success": false in the body. Mid-level developers know the common codes but confuse 401/403 and 400/422. Senior developers understand that status codes are not metadata — they are the primary communication channel between their API and every system that depends on it.

Why HTTP Status Codes Are an API Contract, Not Decoration

When your API returns a status code, you are not annotating a response for a human reader. You are making a machine-readable commitment to every system in your stack about what happened and what they should do next.

Frontend clients depend on them. A React application that receives a 401 should redirect to the login page. A 403 should show an access denied message. A 422 should display field-level validation errors. A 200 OK with {"success": false} gives the frontend nothing actionable — it must parse, interpret, and guess what the right UX response is. Multiply that guesswork across every endpoint your frontend calls and you have an integration that is fragile by design.

API gateways and load balancers depend on them. Kong, AWS API Gateway, NGINX, and every enterprise load balancer make routing, health-checking, and circuit-breaking decisions based on status codes. A node returning consistent 200 OK responses is treated as healthy — even if every response body contains an error. A node returning 503 gets removed from the rotation. Wrong status codes make your infrastructure blind to failure.

Retry libraries depend on them. HTTP clients — Axios, Feign, Spring WebClient, OkHttp — implement retry logic based on status codes. 5xx responses and 429 with Retry-After are retried. 4xx responses are not. An error masked as 200 OK is never retried by any standard HTTP client library. An unretriable request becomes a permanent failure that nobody diagnoses because the error rate dashboard shows zero.

Observability depends on them. Datadog, Prometheus, Grafana, CloudWatch — all surface error rate metrics broken down by status code family. A query for status:5xx AND service:payment-api returns your incidents in seconds. With 200-for-everything, that query returns nothing. The incidents are there, buried in body content that your monitoring infrastructure was never designed to parse. The absence of 5xx alerts is not stability — it is blindness.

Why Wrong Status Codes Break Frontend Retries, Monitoring, and SDKs

The downstream impact is more specific than most engineers realise when they are writing the code:

• Axios interceptors — the standard axios.interceptors.response pattern branches on 401 to trigger token refresh and on 403 to redirect to an error page. A 403 returned for a missing token sends the user to "access denied" instead of the login screen. An interceptor cannot distinguish these without reading the body — which defeats the purpose of HTTP semantics entirely.
• Retry libraries — Spring WebClient, OkHttp, Feign, and Resilience4j retry configurations target 5xx and 429 responses. A transient failure returned as 200 OK is never retried. A rate limit returned as 500 is retried immediately, causing the thundering herd problem the 429 + Retry-After pattern was designed to prevent.
• CDN and reverse proxy caching — Cloudflare, Fastly, and Varnish cache responses based on status code. 200 responses are cached. 404 and 410 responses are not (or are cached briefly). A resource that returns 200 with empty content will be cached and served from edge nodes long after the real resource is available — causing stale content that is invisible to your origin server.
• Kubernetes liveness and readiness probes — httpGet probes interpret any 2xx as healthy. A service returning 200 OK while unable to reach its database appears healthy to Kubernetes and continues receiving traffic. The correct response when a critical dependency is unavailable is 503 — which causes the probe to fail and the pod to be removed from the endpoint slice.
• Mobile SDK clients — iOS and Android SDK implementations branch on status code family (2xx / 4xx / 5xx) before parsing the body. Wrong codes produce wrong SDK-level error types, which means the error handling code the mobile developer wrote for authentication failures will never fire on a 200 OK response — even when the body contains an auth error.

The diagram below shows what a single wrong status code silently breaks across six systems simultaneously — all of which took the 200 OK at face value.

"HTTP status codes are not decoration. They are machine-readable operational truth."

The Senior Developer HTTP Status Decision Tree

Before choosing a status code, answer these questions in order:

Success Responses — 200 vs 201 vs 202 vs 204

The 2xx family is not just "it worked." Each code tells the client something specific about what happened — and those specifics matter to consumers building retry logic, polling mechanisms, and UI flows.

Spring Boot · correct 2xx responses
// GET — return data with 200
@GetMapping("/users/{id}")
public ResponseEntity<UserDto> getUser(@PathVariable Long id) {
    return ResponseEntity.ok(userService.findById(id));  // 200
}

// POST — return 201 with Location header
@PostMapping("/users")
public ResponseEntity<UserDto> createUser(@RequestBody @Valid CreateUserRequest req,
                                           UriComponentsBuilder uriBuilder) {
    UserDto created = userService.create(req);
    URI location = uriBuilder.path("/users/{id}").buildAndExpand(created.id()).toUri();
    return ResponseEntity.created(location).body(created);  // 201 + Location header
}

// DELETE — return 204, no body
@DeleteMapping("/users/{id}")
public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
    userService.delete(id);
    return ResponseEntity.noContent().build();  // 204
}

Authentication & Permission — 401 vs 403

This is the most consistently confused pair in API development. I see them swapped in every third codebase I review. The distinction is precise and operationally important — because clients use these codes to decide whether to re-authenticate.

// BAD — 403 when token is completely missing
if (!hasPermission(user)) {
    return ResponseEntity.status(403).build(); // wrong when user is null
}
// If user is null (unauthenticated), this should be 401, not 403

Spring Boot · correct 401 vs 403 in SecurityFilterChain
http
  // 401 — no valid credentials → redirect to authenticate
  .exceptionHandling(ex -> ex
      .authenticationEntryPoint((req, res, authEx) -> {
          res.setHeader("WWW-Authenticate", "Bearer realm=\"api\"");
          res.sendError(HttpServletResponse.SC_UNAUTHORIZED, "Authentication required");
      })
      // 403 — authenticated but no permission → show access denied
      .accessDeniedHandler((req, res, accessEx) -> {
          res.sendError(HttpServletResponse.SC_FORBIDDEN, "Insufficient permissions");
      })
  );

JWT Auth Failures − Differentiating Expired, Invalid, and Missing

When a client receives a 401 Unauthorized, the immediate question for the frontend is: "Do I need to login again, or is my token simply expired and needs refreshing?". Bespoke error formats often force the client to parse string messages like "Token is expired", which is fragile and error-prone.

RFC 9457 allows you to use distinct type URIs to communicate these states machine-readably, enabling your authorization interceptors to act decisively.

{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Token expired"
}

{
  "type": "https://api.yourdomain.com/probs/token-expired",
  "title": "Token Expired",
  "status": 401,
  "detail": "Credential expired at 2026-05-01T12:00:00Z",
  "expiredAt": "2026-05-01T12:00:00Z"
}

This allows your Axios/Fetch interceptors to branch logic based on the type field. If the type is token-expired, you can automatically trigger a POST /auth/refresh call; if it's invalid-token or missing-token, you redirect to the login page immediately. No string parsing required.

Missing vs Gone vs Conflict — 404 vs 410 vs 409

Validation Failures — 400 vs 409 vs 422

All three deal with "something is wrong with the request" — but they describe different kinds of wrong, and clients need to respond differently to each.

Spring Boot · structured validation error responses
@RestControllerAdvice
public class ApiExceptionHandler {

    // 400 — malformed request (JSON parse failure, wrong Content-Type)
    @ExceptionHandler(HttpMessageNotReadableException.class)
    public ResponseEntity<ErrorResponse> handleMalformed(HttpMessageNotReadableException ex) {
        return ResponseEntity.badRequest()  // 400
            .body(new ErrorResponse("MALFORMED_REQUEST", "Request body could not be parsed"));
    }

    // 422 — validation failure on well-formed request
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ValidationErrorResponse> handleValidation(
            MethodArgumentNotValidException ex) {
        Map<String, String> fieldErrors = ex.getBindingResult().getFieldErrors()
            .stream()
            .collect(Collectors.toMap(FieldError::getField, FieldError::getDefaultMessage));
        return ResponseEntity.unprocessableEntity()  // 422
            .body(new ValidationErrorResponse("VALIDATION_FAILED", fieldErrors));
    }

    // 409 — state conflict
    @ExceptionHandler(ResourceConflictException.class)
    public ResponseEntity<ErrorResponse> handleConflict(ResourceConflictException ex) {
        return ResponseEntity.status(HttpStatus.CONFLICT)  // 409
            .body(new ErrorResponse("CONFLICT", ex.getMessage()));
    }
}

Validation Errors − Field-Level Detail as RFC 9457 Extension

One of the most frequent questions I get in workshops is: "Where do the field-level errors go if they aren't in the standard?". RFC 9457 is intentionally minimal. It defines the core wrapper but encourages the use of Extension Members for problem-specific details. For validation, the industry standard has converged on adding an errors array of objects.

Here is how a production-grade validation extension looks. Notice we include a field and a machine-readable reason alongside the human message:

{
  "type": "https://api.yourdomain.com/probs/validation-error",
  "title": "Validation Failed",
  "status": 422,
  "detail": "The request contained 2 validation errors",
  "instance": "/logs/abc-123",
  "errors": [
    {
      "field": "email",
      "reason": "INVALID_FORMAT",
      "message": "must be a valid email address"
    },
    {
      "field": "age",
      "reason": "MIN_VALUE",
      "message": "must be 18 or older"
    }
  ]
}

Rate Limits and Temporary Failures — 429 vs 503

Spring Boot · 429 with Retry-After header
// Rate limiter fallback — return 429 with Retry-After, never 500
public ResponseEntity<?> rateLimitFallback(RequestNotPermitted e) {
    return ResponseEntity
        .status(HttpStatus.TOO_MANY_REQUESTS)    // 429
        .header("Retry-After", "60")             // seconds until retry is allowed
        .header("X-RateLimit-Limit", "100")
        .header("X-RateLimit-Reset", String.valueOf(Instant.now().plusSeconds(60).getEpochSecond()))
        .body(Map.of(
            "error", "RATE_LIMIT_EXCEEDED",
            "message", "Too many requests. Retry after 60 seconds.",
            "retryAfter", 60
        ));
}

Downstream Service Failures − 503 with Retry Guidance

In microservices, your API is often a orchestrator. When a downstream service (like a payment gateway, database, or a third-party legacy system) is unavailable, returning a generic 500 is an operational lie. It implies your code crashed and alerts your on-call engineer for the wrong reason.

Returning a 503 Service Unavailable with a retryAfter extension member tells the client and the infrastructure exactly how to handle the transient failure.

{
  "type": "https://api.yourdomain.com/probs/service-unavailable",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "The Payment Provider is undergoing scheduled maintenance.",
  "retryAfter": 30,
  "downstreamService": "Stripe"
}

By including retryAfter as an extension (and ideally as a Retry-After HTTP header), you allow automated retry libraries like Resilience4j or Polly to wait for the specified window. This prevents the "thundering herd" effect where thousands of clients retry immediately after a blip, crashing your system just as it tries to recover.

Server Failures — 500 vs 502 vs 503 vs 504

The 5xx family covers everything where the server is at fault, not the client. The specific code tells operators and monitoring systems where to look — in your application, in your gateway, or in your upstream dependencies.

Spring Boot · global exception handler — correct 5xx mapping
@RestControllerAdvice
public class GlobalExceptionHandler {

    // 500 — unexpected application exception
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleUnexpected(Exception ex) {
        log.error("Unhandled exception: {}", ex.getMessage(), ex);
        // NEVER expose internal exception details to the client
        return ResponseEntity.internalServerError()  // 500
            .body(new ErrorResponse("INTERNAL_ERROR", "An unexpected error occurred"));
    }

    // 503 — dependency unavailable (e.g. DB connection pool exhausted)
    @ExceptionHandler(ServiceUnavailableException.class)
    public ResponseEntity<ErrorResponse> handleUnavailable(ServiceUnavailableException ex) {
        return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)  // 503
            .header("Retry-After", "30")
            .body(new ErrorResponse("SERVICE_UNAVAILABLE", "Service temporarily unavailable"));
    }
}

"A client should be able to understand what happened from the status code alone. If they need to parse the body to detect failure — your API is not speaking HTTP."

The Lazy Developer Anti-Pattern: Returning 200 OK for Everything

This is the section that will get shared. Because every developer has seen this code, and many have written it. The "200 OK with error body" pattern is so widespread that some teams have convinced themselves it is a legitimate design choice. It is not. It is an API that lies to every system that calls it.

return ResponseEntity.ok(
    Map.of("success", false, "message", "User not found"));

Java · the 200 OK anti-pattern in all its forms
// Form 1 — success field in body
@GetMapping("/users/{id}")
public ResponseEntity<?> getUser(@PathVariable Long id) {
    User user = userService.findById(id);
    if (user == null) {
        return ResponseEntity.ok(Map.of("success", false, "error", "User not found"));
        // 200 OK — every monitoring tool, retry mechanism, and
        // load balancer thinks this request succeeded. It did not.
    }
    return ResponseEntity.ok(user);
}

// Form 2 — wrapper with status field
{ "status": "error", "code": 404, "message": "Not found" }  // returned with HTTP 200
// The HTTP layer says success. The body says failure.
// Clients must parse the body to know if the request succeeded.
// Every HTTP-aware tool in your infrastructure is now useless.

// Form 3 — RPC-style flat error (common in older Java/XML-RPC style APIs)
{ "result": null, "errorCode": "USR_NOT_FOUND" }  // HTTP 200
// Retry libraries will not retry. Alerts will not fire.
// Error dashboards will show 0% error rate. The bug is invisible.

The downstream consequences are not theoretical. A load balancer that sees consistent 200 OK responses will never circuit-break a failing service. An alerting system configured to alert on 5xx rates will show zero alerts while your users hit errors. A search engine crawler receiving 200 OK on a page that displays "Product not found" will continue to index that page and rank it. Every one of these is a real operational problem that 200 OK masking causes.

The 10 HTTP Status Code Mistakes I Keep Seeing in Real APIs

The same ten mistakes appear in almost every API codebase I review. Bookmark it. Use it in code review.

Real API Examples — What Mature Systems Actually Return

Theory is one thing. Here is how well-designed production APIs from mature engineering organisations actually use these codes.

The 10 HTTP Status Code Mistakes I Keep Seeing in Real APIs

This table ranks independently in search. Bookmark it. Add it to your team wiki. These are not edge cases — they are standard misuses that appear in production systems across every company size.

Real API Response Mistakes I Still See in Production

These are not hypothetical. Every item below is a pattern I have found in a production codebase in the last two years. Some were in systems handling millions of requests per day.

These are not semantic nitpicks. They directly affect client state handling, retry behaviour, dashboard accuracy, and incident diagnosis time. Every one of them added hours to a debugging session that would have been obvious with the correct code.

Senior Developer HTTP Status Code Cheat Sheet

Bookmark this. One table covering every production scenario by response class.

Senior Developer HTTP Response Checklist

Use this before shipping any new API endpoint or reviewing an existing one.

• POST that creates a resource returns 201 with a Location header pointing to the new resource 201 Created
• DELETE returns 204 with no response body 204 No Content
• Async operations return 202 with a job ID and status polling URL 202 Accepted
• Missing resource returns 404 — permanently deleted resource returns 410 404 vs 410
• Unauthenticated requests return 401 with WWW-Authenticate header 401 Unauthorized
• Authenticated-but-unauthorised requests return 403, not 401 403 Forbidden
• Malformed request bodies return 400 — validation failures on valid bodies return 422 400 vs 422
• State conflicts (duplicate email, locked resource) return 409 409 Conflict
• Rate limit exceeded returns 429 with Retry-After header 429 Too Many
• Temporary service unavailability returns 503 with Retry-After, not 500 503 vs 500
• Upstream timeout returns 504, upstream bad response returns 502 502 vs 504
• No endpoint returns 200 OK with error content in the body Anti-pattern
• 500 responses never include stack traces, exception class names, or SQL error text Security
• Error responses include a machine-readable error code alongside the human message Integration

FAQ — HTTP Status Codes for REST APIs

Senior Developer HTTP Status Code Cheat Sheet

Bookmark this. Print it. Add it to your team wiki. This is the condensed reference version of everything above — sorted by scenario for fast lookup.