My wife and I were both employed in Nepal at one point for a U.S.-based corporation. Since the platform we worked on was an online food ordering e-commerce system, problems frequently occurred at night. We would receive emails informing us of clients experiencing order placement mistakes or other unforeseen mishaps.

I put in place global exception handling, which automatically emailed the support staff with error alerts to guarantee seamless operations. In this manner, if something went wrong, we’d know right away and could fix it before too many consumers were impacted. Having real-time alerts was essential because order failures could result in lost business.

But as a core developer, I frequently found myself working directly to resolve these problems, sometimes on the weekends or in the middle of the night.

I can still clearly recall one specific instance: I received the call at midnight. Our largest client was unable to fulfill orders because a crucial API service was unavailable. I discovered the cause after searching through countless log files: “Object reference not set to an instance of an object” was a mysterious error message with no context. No trace of the stack. No request ID. I couldn’t figure out what went wrong.

I will never forget the lesson I learned that night: effective error handling is not merely a nice-to-have; it is necessary.

I’ve spent the last decade building and maintaining .NET APIs, and I’ve seen firsthand how error handling can make or break a project. In this article, I’ll share what I’ve learned through trial and error, and many late-night debugging sessions.

The Evolution of Error Handling in .NET

When I first started working with .NET back in the Web Forms days, error handling was mostly an afterthought. We’d wrap some code in try-catch blocks, maybe redirect to an error page, and call it a day. Each developer had their own approach, leading to inconsistent implementations across projects.

Those were simpler times. Today’s distributed systems are far more complex, with microservices communicating across networks and countless potential points of failure.

ASP.NET Core brought a much-needed focus on standardized error handling. Microsoft embraced industry standards like RFC 7807 (Problem Details for HTTP APIs), and the framework now provides robust tools for handling exceptions and returning appropriate responses.

But having tools available doesn’t mean they’re being used effectively. I still encounter APIs that return nothing but a 500 status code when something goes wrong – leaving developers to guess what happened and how to fix it.

Why Good Error Handling Matters

Last year, I consulted for a company that was losing customers due to API reliability issues. Their logs were filled with exceptions, but the error responses provided to clients were so vague that even their own front-end team couldn’t figure out what was going wrong.

After implementing a comprehensive error-handling strategy, two things happened:

1. Support tickets decreased significantly
2. Average time-to-resolution for issues dropped by almost 70%

The reason was simple: developers could now understand what was happening and fix problems faster.

Good error handling isn’t just about catching exceptions – it’s about providing meaningful information that helps developers understand and address issues quickly. Here’s why it matters:

• Developer Experience: I’ve been on both sides of an API, and nothing frustrates me more than cryptic error messages. Clear error responses save hours of debugging time.
• Troubleshooting: When something goes wrong in production, you need to move fast. Standardized error formats with correlation IDs make tracking down issues much easier.
• Security: Proper error handling prevents sensitive information leaks while still providing actionable feedback.
• User Experience: Let’s face it – errors will happen. Good error handling allows you to translate technical issues into user-friendly messages.
• Reliability: A consistent approach to error handling makes your API more predictable and robust.

HTTP Status Codes: Speaking the Language of Web APIs

HTTP status codes are the first line of communication when something goes wrong. Using them correctly is essential for building a professional API.

During a recent code review, I spotted an endpoint that returned a 200 OK status with an error message in the response body. This anti-pattern confuses clients and breaks conventions that other developers expect.

Here’s a quick refresher on the most important status codes for APIs:

2XX – Success

• 200 OK: The request succeeded (for GET requests)
• 201 Created: A new resource was successfully created (for POST requests)
• 204 No Content: The request succeeded, but there’s nothing to return (often used for DELETE)

4XX – Client Errors

• 400 Bad Request: The client sent something invalid (malformed JSON, invalid parameters, etc.)
• 401 Unauthorized: Authentication is required but wasn’t provided
• 403 Forbidden: The client is authenticated but doesn’t have permission
• 404 Not Found: The requested resource doesn’t exist
• 409 Conflict: The request conflicts with the current state (e.g., creating a duplicate resource)
• 422 Unprocessable Entity: The request was well-formed but had semantic errors

5XX – Server Errors

• 500 Internal Server Error: Something unexpected went wrong on the server
• 502 Bad Gateway: An upstream service returned an invalid response
• 503 Service Unavailable: The server is temporarily unavailable (maintenance, overloaded)

I’ve seen too many APIs that return 500 for every error, regardless of the cause. This makes it impossible for clients to handle errors intelligently. Always return the most specific status code that applies to the situation.

Building a Robust Error Handling System in .NET

Let’s dive into practical implementation. I’ll share code examples from real projects (with names changed to protect the innocent) and explain the reasoning behind each approach.

1. Global Exception Handling

The foundation of any good error-handling strategy is global exception handling. This ensures that unhandled exceptions don’t result in default error pages or, worse, expose sensitive information.

I use a middleware approach in all my projects:

ErrorResponse.cs

ExceptionHandlingExtensions.cs

This approach has several benefits

• It ensures all unhandled exceptions return a consistent response format
• It maps custom exceptions to appropriate HTTP status codes
• It includes a trace ID for correlation with logs
• It follows the RFC 7807 standard for problem details

2. Controller-Level Error Handling

While global handlers catch unhandled exceptions, I often implement more specific error handling at the controller level. This provides finer control and allows for custom responses for different scenarios.

Here’s an example from a product management API I built:

Notice the ProducesResponseType attributes. These document the possible responses in Swagger/OpenAPI, making it easier for API consumers to understand what to expect.

3. Input Validation

In my experience, a significant portion of API errors are caused by invalid input. .NET provides several options for validation:

Using Data Annotations

This is the simplest approach and works well for basic scenarios:

Using FluentValidation

For more complex validation scenarios, I prefer FluentValidation. It’s more flexible and allows for context-dependent validation rules: