TypeScript Discriminated Unions: How to Handle Different API Responses Safely

Now add another variant:

type RateLimitedResponse = {
  status: "rate_limited";
  retryAfterSeconds: number;
};

Include it in the union:

type ApiResponse =
  | {
      status: "success";
      data: {
        id: number;
        name: string;
      };
    }
  | {
      status: "validation_error";
      message: string;
      field: string;
    }
  | {
      status: "not_found";
      message: string;
    }
  | RateLimitedResponse;

TypeScript now reports an error at the assertNever(response) call because response may still be a rate-limited response.

Add a corresponding case:

case "rate_limited":
  return `Try again in ${response.retryAfterSeconds} seconds`;

The error disappears once the new variant is handled.

This pattern is particularly useful in larger applications where API response types are shared across components and services.

5. Model Loading, Success, and Error States in React

Discriminated unions are also useful for managing asynchronous UI state.

A common approach is to maintain several separate state variables:

const [loading, setLoading] = useState(false);
const [user, setUser] = useState<User | null>(null);
const [error, setError] = useState<string | null>(null);

This can represent impossible combinations. For example, the application could accidentally have loading set to true while also displaying an old error and a user object.

A discriminated union can represent the state as one value instead.

type User = {
  id: number;
  name: string;
};

type UserState =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; user: User }
  | { status: "error"; message: string };

The state now has four clearly defined variants.

In a React component, you can use it like this:

import { useState } from "react";

type User = {
  id: number;
  name: string;
};

type UserState =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; user: User }
  | { status: "error"; message: string };

function UserProfile() {
  const [state, setState] = useState<UserState>({
    status: "idle"
  });

  async function loadUser() {
    setState({ status: "loading" });

    try {
      const response = await fetch("/api/users/101");

      if (!response.ok) {
        throw new Error(`Request failed: ${response.status}`);
      }

      const user = await response.json() as User;

      setState({
        status: "success",
        user
      });
    } catch {
      setState({
        status: "error",
        message: "Unable to load the user."
      });
    }
  }

  return (
    <div>
      <button onClick={loadUser}>Load user</button>

      {state.status === "loading" && <p>Loading user...</p>}

      {state.status === "success" && (
        <p>Welcome, {state.user.name}</p>
      )}

      {state.status === "error" && (
        <p>{state.message}</p>
      )}
    </div>
  );
}

export default UserProfile;

The component uses one state variable to represent the current UI state. TypeScript ensures that the user property is accessed only after the state has been narrowed to success.

There is one important limitation in this example: response.json() as User tells TypeScript to treat the parsed data as a User, but it does not validate the actual JSON. Type assertions do not check runtime data.

For production applications, validate API responses when they cross the application boundary, especially when the backend schema may change or the response comes from an external service.

6. Handle API Responses from Unknown JSON Safely

TypeScript types are removed during compilation. They do not automatically validate data received from a server.

Suppose the API is expected to return:

{
  "status": "success",
  "data": {
    "id": 101,
    "name": "Aarav Sharma"
  }
}

The server might accidentally return a missing name, a string instead of a number for id, or an entirely different structure.

This code does not validate the response:

const result = await response.json() as ApiResponse;

It only tells the compiler to trust the value.

A safer starting point is to treat the parsed response as unknown:

const result: unknown = await response.json();

You can then validate the shape before using it. For a small example, a type guard can check the fields needed by the application:

type User = {
  id: number;
  name: string;
};

function isUser(value: unknown): value is User {
  if (typeof value !== "object" || value === null) {
    return false;
  }

  const candidate = value as Record<string, unknown>;

  return (
    typeof candidate.id === "number" &&
    typeof candidate.name === "string"
  );
}

Use the guard before accessing the user:

async function fetchUser(): Promise<User> {
  const response = await fetch("/api/users/101");

  if (!response.ok) {
    throw new Error(`Request failed: ${response.status}`);
  }

  const result: unknown = await response.json();

  if (!isUser(result)) {
    throw new Error("The API returned an invalid user response.");
  }

  return result;
}

This example validates a direct User object. If your API wraps the user inside a response envelope, validate the envelope and its nested data as well.

For complex response structures, a runtime schema validation library can make these checks easier to maintain.

7. Avoid Common Discriminated Union Mistakes

Using a general string instead of literal values

This definition is less useful:

type Response = {
  status: string;
  message?: string;
};

Because status can be any string, TypeScript cannot use it to distinguish specific response variants reliably.

Prefer literal values such as "success", "error", and "not_found".

Making every property optional

A type containing many optional properties allows combinations that should not exist. A success response might have no data, while an error response might accidentally contain success-only fields.

Define each variant with its required properties instead.

Assuming types validate external data

Discriminated unions provide compile-time checks. They do not guarantee that incoming JSON matches the declared type.

Validate untrusted data before treating it as a trusted application model.

Forgetting to handle newly added variants

Use an exhaustive switch with a never check when every known case must be handled. This helps detect missing branches as the API evolves.

Conclusion

TypeScript discriminated unions make it easier to represent API responses that have different shapes. By using a shared property such as status, you can let TypeScript identify the active response type and restrict access to the fields that belong to it.

They are useful for API error handling, React loading states, authentication flows, payment results, and other situations where an application can be in one of several distinct states.

Combine discriminated unions with exhaustive checks and runtime validation at API boundaries. This gives you clearer code, fewer invalid state combinations, and better protection against unexpected server responses.