Rethinking Exception Handling in APIs: Design for Clarity, Not Convenience

Many projects—especially APIs—tend to lean too heavily on exceptions, often treating them as a lazy shortcut to communicating failure. I've encountered too many APIs where exceptions escape into the wild or worse, are dumped wholesale into responses. This approach might be convenient for the developer, but it creates a nightmare for API consumers.

In a well-designed API, exceptions should never escape unhandled. They should be caught and translated into meaningful, informative responses. While exceptions are indeed useful during development and debugging, they are rarely intended for end users or external systems.

That doesn’t mean we hide everything behind a vague 500 error. Quite the opposite. A well-crafted response can be clear and helpful without exposing raw internals. Think about what exception type occurred, and use that as a cue to shape your response. But don’t return something like: "We got exception: NullPointerException". Instead, use the exception to inform your API logic and produce a clean, actionable response.

The problem is that most exceptions only carry a message—usually something meant for internal developers. That message isn’t appropriate for API consumers. But what if we enriched exceptions so they carried more useful, structured information?

Enriching Exceptions

This is absolutely achievable. Yes, it takes a shift in mindset, and it might mean creating some supporting structures, but the payoff is significant. Let's go through some examples of what might be achieved.

Dual Messages

Enhance your exceptions to include two messages:

• One for internal diagnostics (e.g., logs).
• One tailored for the external consumer (e.g., API response).

This separation ensures that developers have the information they need without confusing or overwhelming the API consumer. It also helps prevent accidental leaks of sensitive or overly technical details.

Context Flag

Add a simple boolean flag indicating whether the error is due to the consumer (e.g., bad request) or internal server logic. This tiny addition can guide how the API responds and what information is revealed.

For example, the tailored message meant for external consumers might be included in the response if the context flag indicates a bad request. In contrast, if the issue is internal, exposing that message might be unhelpful—or even misleading—for the requester. The flag becomes a simple yet powerful mechanism for deciding what gets communicated and when.

The Result

By implementing just these two small changes, you can radically improve your API's user experience. Instead of cryptic error codes or raw stack traces, your consumers get clear, relevant, and actionable responses—without sacrificing internal visibility.

A Practical Implementation Example

Let's imagine a super class. Something along these lines:

public class ServiceGeneratedException extends Exception {
  private String internalMessage;
  private String externalMessage;
  private boolean causedByExternal;

  public ServiceGeneratedException(String internal, String external, boolean causedByExternal) {
    this.internalMessage = internal;
    this.externalMessage = external;
    this.causedByExternal = causedByExternal;
  }
}

From there we can make two subclasses, one for each case for causedByExternal.

public class InternalException extends ServiceGeneratedException {
  public InternalException(String internal, String external) {
    super(internal, external, false);
  }
}

public class ExternalException extends ServiceGeneratedException {
  public ExternalException(String internal, String external) {
    super(internal, external, true);
  }
}

All your exceptions should inherit from one of these two classes.

This might not look like much at first, but it demonstrates how deliberate changes can lead to impactful improvements.&##x20;

Having these classes provide the opportunity to create more useful responses. We can provide those responses in various formats based on the headers provided. We would have the same data presented in whichever format the requester supports.

What we need is a method that can convert a ServiceGeneratedException to a response body, and then serialize that response into a format that the requester supports. One way to achieve this would be to add something like String toResponse(Set supportedFormats) to ServiceGeneratedException.

The DataFormat here is an enum with entries for JSON, Yaml, XML, and whichever other format you might support. The set supportedFormats is the translation of which formats the requester supports in the response which is found in the request headers.

Here's a simplified implementation

public String toResponse(Set supportedFormats) {
  DataFormat format = findFormatWeCanProduce(supportedFormats)

  // Create a basic response object
  Map response = new HashMap<>();
  response.put("error", this.causedByExternal ? this.externalMessage : "An unexpected error occurred.");
  response.put("type", this.causedByExternal ? "external" : "internal");
  // Other data that could be provided:
  // - Correlation ID
  // - Trace ID
  // - A GUID for this particular issue, making it easier to find it later in the logs.
  //   Just make sure the GUID shows up in the logs as well!

  // Serialize the response to the preferred format
  switch (format) {
    case JSON:
      return JsonSerializer.serialize(response);
    case XML:
      return XmlSerializer.serialize(response);
    case Yaml:
      return YamlSerializer.serialize(response);
    default:
      return JsonSerializer.serialize(response); // fallback
  }
}

A quick word on findFormatWeCanProduce: we assume it selects the first mutually supported format from the set provided. This keeps things simple and pragmatic. If you want to take this further, you could return a strategy object responsible solely for serializing the response body. For example, it might serialize into JSON, XML, or YAML, and potentially include format-specific metadata such as MIME types—relevant in protocols like HTTP.

Separately, the toResponse method itself could delegate to another strategy object tasked with constructing the complete response. This object would be responsible for wrapping the serialized body in whatever envelope is appropriate for the communication protocol, including headers, status codes, and similar metadata. This design helps decouple concerns: one strategy focuses on how data is formatted, and the other on how that formatted data is packaged and delivered within the specific context of a given protocol.

Have you noticed that none of the implementation so far is specific to any one specific communication protocol? This can be used just as well in HTTP, gRPC, RabbitMQ, GraphQL, or whatever! And without affecting your internal implementation to any significant degree.

Final Thoughts: Designing with the Consumer in Mind

Exception handling shouldn't be an afterthought. The API is the contract you offer your consumers—not the exceptions themselves. While exceptions can be wrapped into the API’s response, they must be filtered, reformatted, and made useful. Just because an exception message makes sense to you as the developer doesn't mean it will make any sense to your consumers. Design your error responses with the same care and intention as your successful ones.