Forem: LiavZi

Designing Error Flows: Exceptions, Success Flags, or Discriminated Unions?

LiavZi — Thu, 19 Feb 2026 15:18:17 +0000

The examples in this post are available in a demo repository here: https://github.com/liavzi/DesigningErrorFlows.

Introduction

Recently, I needed to integrate with an external API to synchronize data. From past experience, I have learned that failures are not a question of if but when. Network issues, timeouts, validation errors, authentication failures, unexpected payloads, and third-party outages can all cause requests to fail, often at the worst possible moment.

To make the system more resilient and easier to support, I decided to persist every failed request in the database and capture as much context as possible. This included the request payload, the response when available, and as many details as possible about the nature of the error.

Let’s explore three approaches to designing an API call with errors in mind. For simplicity, assume the call can produce only four outcomes: success with data, an authentication error, a validation error, or a general error.

Exception-Oriented Flow

public class ApiServiceExceptionsOriented(HttpClient httpClient)
{
    public async Task<TResponse> Post<TResponse>(string url, object payload)
    {
        string accessToken;
        try 
        {
            accessToken = await GetAccessToken();
        }
        catch (Exception)
        {
            throw new AuthenticationException("Failed to get access token");
        }
        var httpRequest = new HttpRequestMessage();
        httpRequest.Content = JsonContent.Create(payload);
        httpRequest.Headers.Add("Authorization", $"Bearer {accessToken}");
        var httpResponse = await httpClient.SendAsync(httpRequest);

        if (httpResponse.StatusCode == HttpStatusCode.BadRequest) {
            var validationErrorResponse = await httpResponse.Content.ReadFromJsonAsync<ExternalApiValidationErrorResponse>();
            throw new ValidationException(validationErrorResponse);
        }

        if (!httpResponse.IsSuccessStatusCode) {
            var rawResponse = await httpResponse.Content.ReadAsStringAsync();
            throw new GeneralApiException(rawResponse);
        }

        var response = await httpResponse.Content.ReadFromJsonAsync<TResponse>();
        return response;
    }

    public async Task<string> GetAccessToken()
    {
        return "SOME_ACCESS_TOKEN";
    }
}

Here is what an example call might look like:

public async Task<SyncEmployeeResponse> CallApiExample()
{
    var syncEmployeeRequest = new SyncEmployeeRequest();
    try 
    {
        var response = await Post<SyncEmployeeResponse>("https://some.api/sync-employee", syncEmployeeRequest);
        // other logic
        return response;
    }
    catch (AuthenticationException ex)
    {
        // Handle authentication failure
        throw;
    } catch (ValidationException ex)
    {
        // Handle validation failure, access details via ex.ValidationErrorResponse and maybe show them to the user
        throw;
    } catch (GeneralApiException ex)
    {
        // Handle other API failures, maybe log the error details (ex.Message contains the raw API response)
        throw;
    }
}

The main advantage of this approach is its simplicity on the happy path. You call the API, receive a response, and continue with your logic. However, this simplicity is also its primary drawback.

When an error occurs, you must handle each one in its own catch block. This not only clutters the code but also introduces additional challenges, such as variable scope. If you need access to variables declared inside the try block, you are often forced to move their declarations to an outer scope, which reduces readability and weakens encapsulation.

Moreover, the caller has no clear understanding of which errors might be thrown by the API call. Instead, they must dig into the implementation to discover the possible exceptions. This increases the risk of unhandled errors and can easily lead to future bugs, especially when new failure modes are introduced, such as a rate limit error.

Success Flags

public async Task<ApiCallResult<TResponse>> Post<TResponse>(string url, object payload)
{
    string accessToken;
    try 
    {
        accessToken = await GetAccessToken();
    }
    catch (Exception)
    {
        return new ApiCallResult<TResponse> { IsAuthenticationFailure = true };
    }
    var httpRequest = new HttpRequestMessage();
    httpRequest.Content = JsonContent.Create(payload);
    httpRequest.Headers.Add("Authorization", $"Bearer {accessToken}");
    var httpResponse = await httpClient.SendAsync(httpRequest);

    if (httpResponse.StatusCode == HttpStatusCode.BadRequest) {
        var validationErrorResponse = await httpResponse.Content.ReadFromJsonAsync<ExternalApiValidationErrorResponse>();
        return new ApiCallResult<TResponse>
        {
            ValidationErrorResponse = validationErrorResponse,
        };
    }

    if (!httpResponse.IsSuccessStatusCode) {
        var rawResponse = await httpResponse.Content.ReadAsStringAsync();
        return new ApiCallResult<TResponse>
        {
            HasGeneralFailure = true,
            ErrorRawResponse = rawResponse,
        };
    }

    var response = await httpResponse.Content.ReadFromJsonAsync<TResponse>();
    return new ApiCallResult<TResponse>
    {
        Data = response
    };
}

Now, instead of relying on exceptions, we return an ApiCallResult<T> object that explicitly represents the outcome of the operation:


public class ApiCallResult<T>
{
    public T Data { get; set; }
    public ExternalApiValidationErrorResponse ValidationErrorResponse { get; set; }
    public string ErrorRawResponse { get; set; }
    public bool HasGeneralFailure { get; set; }
    public bool IsSuccess => Data != null;
    public bool IsAuthenticationFailure { get; set; }
}

Now the caller can examine the object and decide how to proceed based on the different flags it exposes:

public async Task CallApiExample()
{
    var syncEmployeeRequest = new SyncEmployeeRequest();
    var callResult = await Post<SyncEmployeeResponse>("https://some.api/sync-employee", syncEmployeeRequest);
    switch (callResult)
    {
        case { IsSuccess: true }:
            // Handle success. can access the response data via callResult.Data
            break;
        case { IsAuthenticationFailure: true }:
            // Handle authentication failure
            break;
        case { ValidationErrorResponse: { } }:
            // Handle validation errors
            break;
        case { HasGeneralFailure: true }:
            // Handle general API failure
            break;
    }

}

We improved the readability of the code and encouraged the caller to think about failure scenarios rather than focusing only on the happy path.

However, the caller still needs to understand and examine the ApiCallResult class to determine which fields are populated for each possible outcome. This implicit contract can become harder to maintain as new error types are introduced.

Moreover, if a new error type is added, we must remember to handle it across all call sites. This raises an important design question: can we force the caller to handle new error types instead of relying on memory and code reviews?

Discriminated Unions

Let’s take this one step further and model the result as a discriminated union.

Instead of returning a single object with multiple nullable fields or boolean flags, we define a closed set of possible outcomes, where each case represents exactly one valid state:

Success with data
Authentication error
Validation error
General error

public abstract record ApiResult<TData>
{
    private ApiResult() { }

    public sealed record SuccessResult(TData Data) : ApiResult<TData>;

    public sealed record ValidationFailedResult(ExternalApiValidationErrorResponse ValidationErrorResponse) : ApiResult<TData>;

    public sealed record GeneralFailureResult(string ErrorRawResponse) : ApiResult<TData>;

    public sealed record AuthenticationFailure : ApiResult<TData>;
}

Now every outcome, whether success or a specific error type, has its own class and its own data. There are no boolean flags and no need to guess which property might be null.

Each case represents a single, valid state. A success contains data. A validation error contains validation details, and so on. The structure itself communicates the intent clearly.

This eliminates invalid combinations, improves readability, and makes the contract between the API call and its caller explicit and self-documenting.

Let’s look at the implementation of the Post method:

public async Task<ApiResult<TResponse>> Post<TResponse>(string url, object payload)
{
    string accessToken;
    try 
    {
        accessToken = await GetAccessToken();
    }
    catch (Exception)
    {
        return new ApiResult<TResponse>.AuthenticationFailure();
    }
    var httpRequest = new HttpRequestMessage();
    httpRequest.Content = JsonContent.Create(payload);
    httpRequest.Headers.Add("Authorization", $"Bearer {accessToken}");
    var httpResponse = await httpClient.SendAsync(httpRequest);

    if (httpResponse.StatusCode == HttpStatusCode.BadRequest) {
        var validationErrorResponse = await httpResponse.Content.ReadFromJsonAsync<ExternalApiValidationErrorResponse>();
        return new ApiResult<TResponse>.ValidationFailedResult(validationErrorResponse);
    }

    if (!httpResponse.IsSuccessStatusCode) {
        var rawResponse = await httpResponse.Content.ReadAsStringAsync();
        return new ApiResult<TResponse>.GeneralFailureResult(rawResponse);
    }

    var response = await httpResponse.Content.ReadFromJsonAsync<TResponse>();
    return new ApiResult<TResponse>.SuccessResult(response);
}

We generate a concrete class for every possible outcome. Notice how much more readable this is compared to the “flags” approach.

In addition, the caller is now required to consider the different result types and handle them appropriately:

public async Task CallApiExample()
{
    var syncEmployeeRequest = new SyncEmployeeRequest();
    var callResult = await Post<SyncEmployeeResponse>("https://some.api/sync-employee", syncEmployeeRequest);
    switch (callResult)
    {
        case ApiResult<SyncEmployeeResponse>.SuccessResult successResult:
            // Handle success. can access the response data via successResult.Data
            break;
        case ApiResult<SyncEmployeeResponse>.AuthenticationFailure:
            // Handle authentication failure
            break;
        case ApiResult<SyncEmployeeResponse>.ValidationFailedResult validationFailedResult:
            // Handle validation errors
            break;
        case ApiResult<SyncEmployeeResponse>.GeneralFailureResult generalFailureResult:
            // Handle general API failure
            break;
        default:
            throw new NotSupportedException("Unknown result type");
    }

}

Notice the default branch. It acts as a safety net, ensuring that if a new error type is introduced and not explicitly handled, it will fail at runtime rather than silently being ignored.

The reason we model ApiResult as a closed hierarchy is intentional. By limiting inheritance to a fixed set of known types, we define a finite set of possible outcomes. This makes the design explicit and controlled.

Even more importantly, this opens the door to stronger compile-time guarantees. If, in the future, the language or our implementation enforces exhaustive pattern matching over a closed hierarchy, the compiler will be able to require callers to handle all possible result types. At that point, adding a new error case would immediately surface compile errors in every unhandled call site, forcing correct handling at compile time rather than relying on runtime behavior.

Final Thoughts

As always, there is no silver bullet.

The discriminated union approach is very explicit, but if we apply it to every method, we may end up with switch expressions and conditional handling scattered throughout the codebase. This is one of the strongest advantages of exceptions: you can continue with the natural flow of the program, and if something goes wrong, you throw and let a higher level in the call chain decide how to handle it.

So in the end, it comes down to intent.

If you want to force the caller to at least think about the possible error cases, use a discriminated union or a success-result object. Both approaches make failure explicit and part of the method’s contract.

If you want to preserve a clean and linear flow while centralizing error handling, exceptions are often the more natural and practical choice.

The key is not to choose one approach blindly, but to understand the trade-offs and use each tool where it fits best (as always 🙂).

Building a Custom TypeScript Client for Your REST API

LiavZi — Mon, 17 Nov 2025 21:58:11 +0000

The examples in this post are available in a demo repository here: https://github.com/liavzi/custom-open-api-ts-client.

The Motivation

In one of the projects I'm working on, we use a simple API service to communicate with the server:

export class ApiService {
  private baseUrl = '';

  constructor() {
  }

  get(endpoint: string): Observable<any> {
    ...
  }

  post(endpoint: string, body: any: Observable<any> {
    ...
  }
}

// when I need to use it
apiService.get("iHateToCopyThisEveryTime").subscribe(response: AnotherTypeINeedToManuallyCreateEveryTime) => {});

The first problem is that I always have to manually pass the endpoint URL. This usually means copy pasting it from the backend, which is repetitive and easy to mess up.

The second problem is even worse: whenever I need to GET or POST json data, I also need to manually create a matching TypeScript interface that represents the server’s request or response model. This is tedious and error prone. If someone changes a property name or adds a new field on the server and forgets to update the client, things break silently.

So the goal became clear: automatically generate a TypeScript client. Whenever an API endpoint is added or changed on the server, the client should get a matching, fully typed function, automatically. No more copy-pasting URLs, no more mismatched interfaces, and no more guessing. Just calling strongly typed functions that feel like any other regular TypeScript function.

Before Diving In

I’m using ASP.NET Core on the backend and Angular on the frontend, but the general idea works with almost any tech stack.
Here, I’m using the Hey API package to generate TypeScript models. This package can also generate full Angular, React, and other clients. However, I ran into a challenge: I wanted to integrate it into an existing project that already had a service handling API calls. Merging the two wasn’t straightforward, so I decided to use Hey API solely for model generation.

The Plan

Generate an OpenAPI specification automatically on every server build.
Generate the request and response models from that spec using Hey API.
Generate matching client API services,one for each controller on the server, so the frontend always has up-to-date, fully typed functions.

Generate an OpenAPI specification automatically on every server build

ASP.NET Core supports OpenAPI out of the box, so generating the specification is pretty straightforward:

using Backend.OpenApi;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi
builder.Services.AddOpenApi("internal-api", options =>
{
    options.AddOperationTransformer(new AddMethodNameOperationTransformer());
});

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseAuthorization();

app.MapControllers();

app.Run();

Pay special attention to the following line, which adds a custom operation transformer:

options.AddOperationTransformer(new AddMethodNameOperationTransformer());

and the code of the transformer:

using Microsoft.AspNetCore.Mvc.Controllers;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.OpenApi;

namespace Backend.OpenApi;

public class AddMethodNameOperationTransformer : IOpenApiOperationTransformer
{
    public async Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransformerContext context,
        CancellationToken cancellationToken)
    {
        if (context.Description.ActionDescriptor is not ControllerActionDescriptor controllerActionDescriptor)
            return;
        operation.AddExtension("x-method-name", new JsonNodeExtension(controllerActionDescriptor.ActionName));
    }
}

Thanks to the transformer, the generated OpenAPI spec will now include the actual C# method name as part of the operation metadata. This becomes extremely helpful when generating the TypeScript client, because we can produce clean, predictable function names instead of trying to infer them from routes.
For example, consider an API endpoint that returns a list of books:

[HttpGet]
public IEnumerable<Book> GetAllBooks()
{
    return Books;
}

It appears in the generated JSON like this:

"/api/Books": {
      "get": {
        "tags": [
          "Books"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Book"
                  }
                }
              },
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Book"
                  }
                }
              },
              "text/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Book"
                  }
                }
              }
            }
          }
        },
        "x-method-name": "GetAllBooks"
      },

Now we want to generate the OpenAPI JSON on every build.
ASP.NET Core makes this straightforward. We can simply follow the official instructions from Microsoft’s documentation.
After that, we add the following lines to the .csproj file:

    <PropertyGroup>
        <OpenApiDocumentsDirectory>$(ProjectDir)../../Frontend/src/app/contracts</OpenApiDocumentsDirectory>
    </PropertyGroup>

    <Target Name="CreateTypescriptClient" AfterTargets="Build" Condition="'$(Configuration)' == 'Debug'">
        <Exec Command="npm run generate-contracts" WorkingDirectory="$(ProjectDir)../../Frontend" />
    </Target>

This configuration instructs the build process to output the generated OpenAPI JSON into the client’s contracts directory.
Then, whenever the project is built in debug mode, it automatically runs the generate-contracts npm script, ensuring your TypeScript client stays in sync with the API definitions.

Client Side Model Generation

Next, we’ll implement the generate-contracts script using the Hey API package.
After installing HeyAPI, add the following scripts to your package.json:

"scripts": {
    "ng": "ng",
    "start": "ng serve",
    ...
    "generate-contracts": "openapi-ts && npm run generate-api-services",
    "generate-api-services": "node src/app/contracts/createApiServices.mjs"
  },

The generate-contracts will now create types directly from the OpenAPI JSON.
Hey API is highly customizable, look at the official documantaion to to see how to configure it using the openapi-ts.config file.

Generate the Client's API Services

Now, here’s the really interesting part. The script createApiServices.mjs
iterates over the OpenAPI JSON and generates custom API services using ts-morph.

Take some time to explore the file and its comments to see exactly how it works under the hood.

For example, check out the BooksApiService, which is one of the services generated by this script:

import { Injectable } from '@angular/core';
import { ApiService, RequestParam } from '../../../api-service';
import { Observable } from 'rxjs';
import { Book } from '@contracts';

@Injectable({ providedIn: 'root' })
export class BooksApiService {
    constructor(private readonly apiService: ApiService) {
    }

    getAllBooks(apiServiceRequestParams?: RequestParam): Observable<Book[]> {
        return this.apiService.handleInternalApiCall({
            url: "/api/Books",
            pathParams: {},
            queryParams: {},
            httpVerb: "get",
            requestBody: undefined,
            apiServiceRequestParams
        });
    }

    addBook(requestBody: Book, apiServiceRequestParams?: RequestParam): Observable<Book> {
        return this.apiService.handleInternalApiCall({
            url: "/api/Books",
            pathParams: {},
            queryParams: {},
            httpVerb: "post",
            requestBody: requestBody,
            apiServiceRequestParams
        });
    }

    getBookByTitle(title: string, apiServiceRequestParams?: RequestParam): Observable<undefined> {
        return this.apiService.handleInternalApiCall({
            url: "/api/Books/title/{title}",
            pathParams: {title},
            queryParams: {},
            httpVerb: "get",
            requestBody: undefined,
            apiServiceRequestParams
        });
    }

    getBooksByAuthor(author: string, apiServiceRequestParams?: RequestParam): Observable<Book[]> {
        return this.apiService.handleInternalApiCall({
            url: "/api/Books/author/{author}",
            pathParams: {author},
            queryParams: {},
            httpVerb: "get",
            requestBody: undefined,
            apiServiceRequestParams
        });
    }
}

As you can see, it aligns perfectly with the server-side controller:

namespace Backend.Controllers
{
    using Microsoft.AspNetCore.Mvc;
    using System.Collections.Generic;

    [ApiController]
    [Route("api/[controller]")]
    public class BooksController : ControllerBase
    {
        private static readonly List<Book> Books = new()
        {
            new Book { Title = "The Hobbit", Author = "J.R.R. Tolkien" },
            new Book { Title = "1984", Author = "George Orwell" },
            new Book { Title = "To Kill a Mockingbird", Author = "Harper Lee" }
        };

        [HttpGet]
        public IEnumerable<Book> GetAllBooks()
        {
            return Books;
        }

        [HttpPost]
        public Book AddBook([FromBody] Book book)
        {
            Books.Add(book);
            return book;
        }

        [HttpGet("title/{title}")]
        public Book? GetBookByTitle(string title)
        {
            return Books.FirstOrDefault(b => b.Title.Equals(title, StringComparison.OrdinalIgnoreCase));
        }

        [HttpGet("author/{author}")]
        public IEnumerable<Book> GetBooksByAuthor(string author)
        {
            return Books.Where(b => b.Author.Equals(author, StringComparison.OrdinalIgnoreCase));
        }
    }

    public class Book
    {
        public required string Title { get; set; }
        public required string Author { get; set; }
    }
}

The amazing part is that this approach frees us from remembering URLs or building query strings - we can just call regular functions. Check out
books.component.ts to see how simple it is to use.

Some might argue that this couples the client to the server’s structure.
But in practice, for internal APIs, I don’t really care about URLs and query strings - they’re just implementation details. All I want is a straightforward way to call my server!

The final piece is implementing the ApiService.
The handleInternalApiCall(args: InternalApiCallArgs) method receives all the information needed to call the server, making integration with your existing project pretty straightforward. You can see my intentionally simplified implementation in the link above.

That’s it! With this setup, generating TypeScript clients from your OpenAPI spec is no longer a chore. You don’t have to worry about URLs, query strings, or boilerplate code - just call the API like a normal function.
Give it a try in your own projects and see how much smoother your development can become.