The common `success: true/false` API pattern is an anti-pattern that breaks standard tooling and hides critical errors. Learn how to leverage native HTTP status codes for more robust, maintainable, and predictable systems.

The ‘success: true’ Lie: Why Your API Responses Are Sabotaging Your Frontend

It was 2 AM on a Tuesday, and my phone was lighting up. Not PagerDuty—that was the scary part. The monitoring dashboards were an ocean of green. All services reported 200 OK. But our support channel was on fire with users reporting that their dashboards were empty, showing nothing but a loading spinner of death. We were blind. After an hour of frantic digging, we found the culprit: a minor, non-critical microservice responsible for user preferences had a database connection issue. Instead of failing with a 500-level error, it dutifully returned a 200 OK with a JSON body: {"success": false, "error": "Cannot connect to prod-db-01"}. Our main monolith API, which called this service, saw the 200 OK and assumed everything was fine. It passed a null preferences object to the frontend, which choked and failed silently. That night, I swore an oath: never again would I let a 200 OK lie to me.

So, What’s the Big Deal? It Works, Right?

I see this pattern everywhere, especially with teams trying to create a “standard” response format. The intention is good: predictability. You always get a JSON object, and you always check a `success` flag. The problem is, you’re fighting the very platform you’re building on. HTTP, the foundation of our web APIs, already has a standardized success/failure mechanism: status codes.

When you stuff your success status inside the JSON payload of a 200 OK response, you break a ton of tools and conventions that are built around HTTP semantics:

• Client Libraries: Tools like Axios, the native `fetch` API, and data-fetching libraries like React Query or SWR are all designed to treat non-2xx status codes as errors. They’ll throw exceptions and trigger `.catch()` blocks or `isError` states automatically. Your `{“success”: false}` pattern bypasses all of that, forcing every single frontend developer to write manual, redundant `if (res.data.success)` checks in every `then()` block.
• Monitoring & Caching: API gateways, load balancers, and monitoring tools are all configured to interpret status codes. A 503 error can trigger a circuit breaker. A 429 can trigger rate-limiting. A 404 can be cached differently than a 200. When every response is a 200, your infrastructure loses all this valuable context.
• Developer Experience: It’s just plain confusing. A junior dev opens the Network tab in their browser, sees a “200 OK,” and spends hours wondering why their data isn’t showing up, only to realize they have to dig into the JSON body to find the “real” status.

Let’s fix this. Depending on your situation, here are a few ways to climb out of this hole.

Solution 1: The Pragmatic Patch (If You’re Stuck With It)

Okay, sometimes you’re working on a legacy system, and you can’t just boil the ocean. A full migration is off the table. If you are absolutely stuck with the `success` flag, the least you can do is make it robust and predictable with a strong contract, especially if you’re using TypeScript.

Instead of a loosey-goosey object, define a discriminated union type for your API responses. This forces developers to handle both the success and failure cases properly.

Enforce a Strict Contract

// A generic type for a successful API response
interface ApiSuccessResponse<T> {
  success: true;
  data: T;
  // Maybe a timestamp, request ID, etc.
  requestId: string;
}

// A specific type for a failed API response
interface ApiErrorResponse {
  success: false;
  error: {
    code: 'VALIDATION_ERROR' | 'UNAUTHENTICATED' | 'SERVER_ERROR';
    message: string;
    details?: Record<string, any>; // Optional field for more context
  };
  requestId: string;
}

// The final type combines them
type ApiResponse<T> = ApiSuccessResponse<T> | ApiErrorResponse;

// Example usage
function handleResponse(response: ApiResponse<User>) {
  if (response.success) {
    // TypeScript knows `response.data` exists here
    console.log(response.data.name);
  } else {
    // TypeScript knows `response.error` exists here
    console.error(`Error (${response.error.code}): ${response.error.message}`);
  }
}

This doesn’t fix the underlying issue of subverting HTTP, but it at least makes the pattern safer and self-documenting on the client-side. It’s a band-aid, but a pretty good one.

Solution 2: The Permanent Fix (Embrace the Platform)

This is the real solution. Use HTTP status codes for what they were invented for: communicating the outcome of a request. The body of the response should contain the requested data on success, or a descriptive error object on failure.

Here’s a simple cheat sheet:

Look how much cleaner and more intuitive the client-side code becomes:

async function fetchUser(userId) {
  try {
    const response = await fetch(`/api/users/${userId}`);

    // The .ok property is true for any 2xx status code
    if (!response.ok) {
      // This block now catches 400, 404, 500, etc.
      // We can even parse a structured error message from the server
      const errorPayload = await response.json();
      throw new Error(errorPayload.message || `HTTP error! Status: ${response.status}`);
    }

    const user = await response.json();
    displayUserData(user);

  } catch (error) {
    // This single catch block handles network failures AND HTTP errors!
    displayErrorState(error.message);
  }
}

No more manual `if` statements in your success path. The error handling is now separate and robust, exactly as it should be.

A Word of Warning: For 500-level errors, never leak sensitive information like stack traces in your response body in a production environment. Return a generic error message and log the detailed exception on the server.

Solution 3: The ‘Nuclear’ Option (Standardize with RFC 7807)

If you’re working in a large organization with dozens of microservices, just “using status codes” might not be enough. You need a consistent, predictable format for your error responses. Enter RFC 7807: Problem Details for HTTP APIs.

This is a formal standard for formatting error payloads. It’s a bit more verbose, but it provides incredible clarity and consistency. It’s the “nuclear” option because it’s a big commitment, but it permanently solves the problem of inconsistent error shapes across your entire architecture.

An RFC 7807 response for a validation error might look like this:

// HTTP/1.1 400 Bad Request
// Content-Type: application/problem+json

{
  "type": "https://api.techresolve.com/errors/validation-error",
  "title": "Invalid request parameters.",
  "status": 400,
  "detail": "The 'email' field must be a valid email address.",
  "instance": "/users",
  "invalid-params": [
    {
      "name": "email",
      "reason": "value is not a valid email"
    }
  ]
}

This is overkill for a small monolith, but for a complex system, it’s a lifesaver. Your client-side error handling logic can be written once and used everywhere, because it can always expect these fields (`type`, `title`, `detail`, etc.) when an API call fails.

Ultimately, the goal is clarity and leveraging the tools we already have. HTTP is a powerful, mature platform. Don’t fight it—embrace it. Your teammates, your monitoring tools, and your future self will thank you.

Darian Vance

Lead Cloud Architect & DevOps Strategist

With over 12 years in system architecture and automation, Darian specializes in simplifying complex cloud infrastructures. An advocate for open-source solutions, he founded TechResolve to provide engineers with actionable, battle-tested troubleshooting guides and robust software alternatives.

🤖 Frequently Asked Questions