为何ASP.NET Core API出错时返回200而非500内部服务器错误？

问题原因 #

你遇到的情况是因为当前非开发环境下配置了UseExceptionHandler("/Error")，这个中间件会捕获服务器端未处理的异常，然后重定向到/Error页面返回HTML内容，同时状态码保持200 OK。这种设计是为了给普通Web页面用户展示友好的错误页面，但对于API请求来说，就会导致客户端拿到非预期的HTML，触发反序列化失败。

是否合理？ #

这是ASP.NET Core针对Web应用的默认合理行为，但不适用于API场景。因为API的客户端（比如你的Blazor WASM应用）期望的是JSON格式的错误信息和对应的错误状态码（比如500），而不是HTML页面。

解决方案：区分API与页面的异常处理 #

要让API请求在出错时返回500状态码和JSON格式错误，需要给API路径单独配置异常处理逻辑，和普通页面的错误处理分开：

1. 修改服务器端中间件配置 #

通过MapWhen匹配API路径（比如以/api开头的请求），为其设置专属的异常处理中间件，返回JSON格式的500错误：

// 优先处理API请求的异常
app.MapWhen(context => context.Request.Path.StartsWithSegments("/api"), apiApp =>
{
    apiApp.UseExceptionHandler(errorApp =>
    {
        errorApp.Run(async context =>
        {
            // 设置500状态码
            context.Response.StatusCode = StatusCodes.Status500InternalServerError;
            context.Response.ContentType = "application/json";

            // 获取异常信息
            var exceptionFeature = context.Features.Get<IExceptionHandlerPathFeature>();
            var errorMsg = exceptionFeature?.Error.Message ?? "发生未处理的服务器错误";

            // 返回JSON格式错误
            await context.Response.WriteAsJsonAsync(new 
            { 
                Code = 500,
                Message = errorMsg,
                Path = exceptionFeature?.Path
            });
        });
    });

    // 配置API相关的路由、授权等中间件
    apiApp.UseRouting();
    apiApp.UseAuthorization();
    apiApp.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
});

// 再处理普通页面的错误逻辑
if (app.Environment.IsDevelopment())
{
    app.UseMigrationsEndPoint();
    app.UseWebAssemblyDebugging();
}
else
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

// 页面相关的中间件（静态文件、Blazor框架文件等）
app.UseHttpsRedirection();
app.UseBlazorFrameworkFiles();
app.UseStaticFiles();
app.UseRouting();
app.UseEndpoints(endpoints =>
{
    endpoints.MapFallbackToFile("index.html");
});

2. 关键注意点 #

• 中间件顺序很重要：API的异常处理逻辑要放在页面错误处理之前，确保API请求先进入专属的异常处理流程。
• 客户端适配：修改服务器端后，客户端可以正常通过response.IsSuccessStatusCode判断请求是否失败，捕获500状态码后直接处理错误信息，无需再尝试反序列化HTML内容。

总结 #

默认的UseExceptionHandler("/Error")是为Web页面设计的，对于API场景需要单独配置。通过区分请求路径设置不同的异常处理逻辑，就能让API在出错时返回标准的500状态码和JSON错误信息，避免客户端的反序列化异常。

内容的提问来源于stack exchange，提问作者CageE