Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/FloppyShelf/Problemize/llms.txt

Use this file to discover all available pages before exploring further.

Problemize provides a robust and extensible framework for centralized exception handling in .NET Web APIs. It standardizes error responses using ProblemDetails and integrates seamlessly with ASP.NET Core.

​
Installation

Install the FloppyShelf.Problemize package from NuGet: 
dotnet add package FloppyShelf.Problemize

​
Setup

1

Configure services

Add exception handling services to your dependency injection container:
Program.cs
using FloppyShelf.Problemize;

var builder = WebApplication.CreateBuilder(args);

// Register exception handling services
builder.Services.UseExceptionHandling();

var app = builder.Build();
The UseExceptionHandling() method automatically configures:
  • ProblemDetails with request metadata (instance, requestId, activityId)
  • Default status code mapping for common exceptions
  • Global exception handler service
2

Configure middleware

Add exception handling middleware to your request pipeline:
Program.cs
// Enable global exception handling
app.UseExceptionHandling();

app.Run();
Call UseExceptionHandling() early in your middleware pipeline to catch exceptions from all subsequent middleware and endpoints.

​
Complete example

Here’s a complete working example: 
using FloppyShelf.Problemize;

var builder = WebApplication.CreateBuilder(args);

// Configure exception handling services
builder.Services.UseExceptionHandling();

// Add controllers
builder.Services.AddControllers();

var app = builder.Build();

// Use exception handling middleware
app.UseExceptionHandling();

app.MapControllers();

app.Run();

​
Response format

All exceptions are automatically converted to standardized RFC 9457 Problem Details responses: 
{
  "type": "ValidationException",
  "title": "An error occured while validating your request",
  "status": 400,
  "detail": "Product name is required",
  "instance": "POST /api/product",
  "requestId": "0HMVP3K7QQE4H:00000001",
  "activityId": "00-1234567890abcdef-1234567890abcdef-00"
}
​
type
string
The exception type name (e.g., ValidationException, KeyNotFoundException)
​
title
string
A short, human-readable summary of the problem type
​
status
integer
The HTTP status code generated by the origin server
​
detail
string
The exception message providing specific details about this occurrence
​
instance
string
The HTTP method and path of the request that caused the error
​
requestId
string
The unique identifier for this request (TraceIdentifier)
​
activityId
string
The distributed tracing activity ID, if available

​
Built-in status code mappings

Problemize automatically maps common .NET exceptions to appropriate HTTP status codes:
Exception TypeStatus CodeDescription
ValidationException400Bad Request
ArgumentNullException400Bad Request
ArgumentOutOfRangeException400Bad Request
InvalidOperationException400Bad Request
FormatException400Bad Request
OverflowException400Bad Request
NullReferenceException400Bad Request
UnauthorizedAccessException401Unauthorized
KeyNotFoundException404Not Found
FileNotFoundException404Not Found
DirectoryNotFoundException404Not Found
NotSupportedException405Method Not Allowed
TimeoutException408Request Timeout
NotImplementedException501Not Implemented
OutOfMemoryException500Internal Server Error
StackOverflowException500Internal Server Error
All other exceptions500Internal Server Error

​
Best practices

Use specific exceptions

Throw specific exception types (e.g., KeyNotFoundException) instead of generic Exception to get accurate HTTP status codes

Meaningful error messages

Provide clear, actionable error messages in your exceptions - they become the detail field in the response

ValidationException for validation

Use ValidationException for input validation errors to get properly formatted validation problem details

Early middleware placement

Register UseExceptionHandling() early in your middleware pipeline to catch all exceptions

​
Next steps

Custom status codes

Learn how to create custom exception-to-status-code mappings

Custom exceptions

Create domain-specific exceptions for your application

Build docs developers (and LLMs) love

Get started for freeTalk to us