Error Handling

Response Envelope

All API responses use a consistent envelope:

public sealed class ApiResponse<T>
{
    public T? Data { get; init; }
    public ApiError? Error { get; init; }
}

Success responses have data populated and error null. Error responses have data null and error populated.

Exception Middleware

The AdsExceptionMiddleware catches all exceptions and maps them to appropriate HTTP responses:

Auth Errors

Authentication failures (401) and authorization failures (403) are also wrapped in the ApiResponse envelope via custom JWT bearer event handlers. No raw status codes — every response is machine-parseable JSON.