In an ASP.NET Core 10 banking API, you change ApiBehaviorOptions.ClientErrorMapping[404].Link, yet Minimal API 404 bodies keep the RFC 9110 type — why, and how do you align both?
answer
- two default tables, one source
- ClientErrorData has Link and Title
- only DefaultProblemDetailsFactory reads the mapping
- fills Type and Title only when null
- CustomizeProblemDetails reaches both sides
basics
~20 sClientErrorMapping is read only by MVC's DefaultProblemDetailsFactory. Minimal API results and the default problem writer take type and title from an internal table instead. Set the type in CustomizeProblemDetails, which both paths invoke, to give every 404 the same type.
solid answer
~40 s`ApiBehaviorOptions.ClientErrorMapping` is an `IDictionary<int, ClientErrorData>`, where `ClientErrorData` has `Link` and `Title`. MVC's options setup pre-fills it from the same internal table the rest of the framework uses, so out of the box both sides agree. But only `DefaultProblemDetailsFactory` reads it: `ControllerBase.Problem()`, `ValidationProblem()` and the `[ApiController]` client-error and model-state bodies. `Results.Problem`, status-code pages, the exception handler and `DefaultProblemDetailsWriter` fill `type` and `title` from the internal table, so a changed `Link` only shows on controllers. The mapping also only fills a null `Type` or `Title`; an explicit `type:` argument wins. To align both, set `type` in `CustomizeProblemDetails`, which the factory and the default writer both run after their defaults, and keep `ClientErrorMapping` for MVC-only tweaks or leave it alone.
code
csharp · 16 linesbuilder.Services.AddControllers()
.ConfigureApiBehaviorOptions(o =>
{
// Controllers only: Minimal APIs and status-code pages never read this.
o.ClientErrorMapping[StatusCodes.Status404NotFound].Link =
"https://errors.example.com/not-found";
});
// Both surfaces: runs after ClientErrorMapping and after the default writer's table.
builder.Services.AddProblemDetails(o => o.CustomizeProblemDetails = ctx =>
{
if (ctx.ProblemDetails.Status == StatusCodes.Status404NotFound)
{
ctx.ProblemDetails.Type = "https://errors.example.com/not-found";
}
});go deeper
Recall that ClientErrorMapping maps a status code to a Link and a Title for MVC controllers' ProblemDetails.
Explain that the mapping only fills null members and that only DefaultProblemDetailsFactory reads it, not Minimal API results.
Diagnose bodies that differ between controllers, Minimal APIs and unmatched routes, and fix them with the callback both paths share.
Decide which single hook owns error-body defaults in a mixed controller and Minimal API service, and keep a second source of truth from creeping in.
## What ClientErrorMapping is `ApiBehaviorOptions` is MVC's option class for API controller behaviour. Its **`ClientErrorMapping`** property is an `IDictionary<int, ClientErrorData>`; **`ClientErrorData`** has two settable properties, `Link` (written to `type`) and `Title`. MVC's `ApiBehaviorOptionsSetup` fills the dictionary from the framework's internal defaults table, so 404 starts as `https://tools.ietf.org/html/rfc9110#section-15.5.5` with title "Not Found", and 500 as section 15.6.1 with "An error occurred while processing your request." You change it with either of: - `builder.Services.AddControllers().ConfigureApiBehaviorOptions(o => ...)` - `builder.Services.Configure<ApiBehaviorOptions>(o => ...)` ## Who reads it | Producer | Reads `ClientErrorMapping`? | Source of default `type` / `title` | |---|---|---| | `ControllerBase.Problem()`, `ValidationProblem()` | yes | the mapping, via `DefaultProblemDetailsFactory` | | `[ApiController]` client-error results such as `NotFound()` | yes | the mapping | | MVC writer for exceptions in controller actions | yes | rebuilt through the factory | | `Results.Problem`, `Results.ValidationProblem` | no | internal table | | Status-code pages, exception handler, `DefaultProblemDetailsWriter` | no | internal table | | A request matching no endpoint | no | internal table, via status-code pages | So in the banking API, `GET /api/accounts/99` on a controller returns your new link, while `GET /api/cards/99` on a Minimal API endpoint, and any mistyped URL, keeps the RFC 9110 one. ## Rules of the factory `DefaultProblemDetailsFactory.ApplyProblemDetailsDefaults` runs in this order: 1. `Status` gets the requested code if it is null. 2. If the mapping has an entry for that status, `Title ??= entry.Title` and `Type ??= entry.Link`; an explicit `title:` or `type:` argument is kept. 3. `traceId` is set from `Activity.Current?.Id`, falling back to `HttpContext.TraceIdentifier`. 4. `CustomizeProblemDetails` from `ProblemDetailsOptions` runs, if configured. Removing an entry from the mapping leaves `type` and `title` null for that status in controller bodies; they are then omitted from the JSON. ## Aligning both surfaces The one hook both sides share is the callback: ```csharp builder.Services.AddProblemDetails(o => o.CustomizeProblemDetails = ctx => { if (ctx.ProblemDetails.Status == StatusCodes.Status404NotFound) { ctx.ProblemDetails.Type = "https://errors.example.com/not-found"; } }); ``` - The default writer invokes it after its own defaults, and the factory invokes it after `ClientErrorMapping`, so the value wins on both sides. - Unlike the mapping, it can use the request, the exception or an extension to decide. - If you also customize `ClientErrorMapping`, the callback overrides it for the members it sets; keep only one owner per member to avoid two sources of truth. Replacing `ProblemDetailsFactory` with your own subclass is the heavier MVC-only alternative; it still leaves Minimal APIs on the internal table. ## Checking the alignment A short test pass catches drift between the surfaces: 1. Call a controller action that returns `NotFound()` from an `[ApiController]`. 2. Call a Minimal API endpoint that returns `Results.Problem(statusCode: 404)`. 3. Request a path that matches no endpoint, with `UseStatusCodePages()` registered. 4. Compare `type`, `title` and the presence of `traceId` across the three bodies. With only `ClientErrorMapping` changed, the first body differs from the other two. With the callback in place, all three match. An integration test that asserts these members for one route of each kind keeps a later refactoring from splitting them again. ## Related switch `ApiBehaviorOptions.SuppressMapClientErrors` turns off the `[ApiController]` conversion of client-error results to ProblemDetails and makes MVC's problem writer write nothing. It does not change the mapping and does not affect Minimal APIs; which statuses `[ApiController]` converts is a controller-conventions topic.
- A controller action calls Problem(statusCode: 404, type: "urn:bank:account-missing"). Which type does the client see?`urn:bank:account-missing`. `DefaultProblemDetailsFactory` only fills `Type` from `ClientErrorMapping` when it is still null, so an explicit argument is kept. A `CustomizeProblemDetails` callback that sets `Type` unconditionally for 404 would still overwrite it, because the callback runs last; guard such callbacks on the current value.
- Does setting SuppressMapClientErrors = true stop ControllerBase.Problem() from producing a ProblemDetails body?No. `Problem()` builds its body through `ProblemDetailsFactory` and returns it as an `ObjectResult`, which is formatted normally. `SuppressMapClientErrors` only stops `[ApiController]` from converting body-less client-error results such as `NotFound()` into ProblemDetails, and makes MVC's problem writer write nothing.
- ClientErrorMapping changes the type of every ProblemDetails the app sends, Minimal APIs included.
- ClientErrorMapping overrides a type passed explicitly to ControllerBase.Problem().
- ClientErrorMapping starts empty, so controllers send no type until you fill it.
- SuppressMapClientErrors = true is how you stop ClientErrorMapping from applying.
- ClientErrorData exposes Type and Detail properties for each status code.