Skip to main content

Notification API Error Handling

Summary​

Error handling is per-handler and shallow. There is no exception-handling middleware, no developer exception page registration, no problem-details service and no endpoint filter that converts exceptions to responses.

Audience​

Engineers, QA, architects, support, security reviewers and DevOps engineers.

Reference Content​

The verified reference material for this topic is set out in the sections below.

Registered error handling​

Program.cs contains no UseExceptionHandler, no UseDeveloperExceptionPage, no UseStatusCodePages and no AddProblemDetails call. The only middleware registered before the endpoints is correlation and Swagger.

Consequently an unhandled exception inside any handler propagates to the ASP.NET Core host defaults rather than to a service-defined error contract.

Handled failures​

Only four failure classes are handled explicitly, all inside handler bodies.

FailureHandlingResponse
Missing required inputGuard clause400 with an anonymous object carrying a single message field
Unknown channel on template createGuard clause400 with a message enumerating the known channels
Record not foundNull check after lookup404 with a small object carrying the identifier and a boolean flag
Publish not acknowledgedBoolean check on the bus resultBare 502 with no body

The one caught exception​

The template test live-send path is the only place in the native API that wraps work in a try-catch. It catches any exception raised while resolving or invoking the channel sender, marks the message failed, stores the exception message on the message row, records a failed delivery attempt, and returns 200 with the failure described in the body.

Consequence: a failed test send is reported as a successful HTTP call. Callers must inspect the delivery status and error fields in the body rather than the status code. The exception message is echoed back to the caller in that error field.

Unhandled failure classes​

The following surface as unhandled exceptions rather than as a defined response.

  • Database connectivity loss or query failure on any endpoint.
  • Persistence constraint violations on template create or update.
  • Broker connectivity failure raised as an exception rather than a false acknowledgement on the publish hook.
  • Exceptions raised inside the dispatcher during the synchronous dispatch hook, other than those the dispatcher itself handles.
  • JSON deserialization failures on a malformed request body, which are handled by framework defaults.

Error body inconsistency​

Four distinct error shapes exist on one surface: the single-message object for 400, the identifier-plus-flag object for 404, the bare status for 502, and the shared envelope's errors dictionary which only the service-information path could ever populate and never does. A client cannot parse Notification errors with one code path.

Correlation on failures​

The correlation identifier is written to the response header by the middleware before the endpoint executes, so it is present on error responses as well as successful ones. It is not included in any error body. Correlating a reported failure to server logs therefore depends on the caller having captured the response header.

Information disclosure​

The template test path returns a raw exception message to the caller. No other path deliberately returns exception text, but because no exception handler is registered, the host's default behavior governs what an unhandled exception discloses, and that depends on the hosting environment configuration rather than on service code.

Verified absence​

  • No problem-details response anywhere on the surface.
  • No error code taxonomy, error identifier or machine-readable error type.
  • No retry-after header on any failure.
  • No structured validation-error collection returned to the caller.

Classification​

Partial.

Requires confirmation​

Whether exception-handling middleware and a problem-details contract are planned, and whether echoing exception text from the template test path is intentional, require confirmation.

See Also​

Keywords​

  • Notification API
  • Error Handling
  • Draft API documentation

Source References​

  • microservices/src/notification-service/Program.cs
  • microservices/src/notification-service/Api/NotificationEndpoints.cs
  • microservices/src/shared-kernel/Middleware/CorrelationIdMiddleware.cs

Revision Information​

  • Status: Draft
  • Last reviewed: 2026-07-21
  • Review cycle: Quarterly