WebAPI中401响应返回text/html而非application/json的问题问询

问题场景 #

在WebAPI控制器方法中，返回401、409、500等状态码时均需返回序列化后的JSON格式错误DTO，其中409、500等状态码正常工作，但401状态码出现异常：

服务器端代码 #

return Unauthorized(new UnauthorizedError() {
    Id = 1, //int
    Error = Error.UserNotFound, //enum
    Message = "User not found"  //string
});

客户端处理代码 #

if (response.StatusCode == HttpStatusCode.Unauthorized)
{
    var result = await response.Content.ReadAsAsync<UnauthorizedError>(ct);
}

客户端抛出异常 #

No MediaTypeFormatter is available to read an object of type 'UnauthorizedError' from content with media type 'text/html'.

原因分析 #

是的，IIS默认会拦截401这类HTTP状态码，自动替换为自带的text/html格式错误页面，导致WebAPI返回的JSON响应被覆盖。

解决方案 #

方案1：配置IIS传递原始响应 #

在项目的Web.config中，找到<system.webServer>节点，添加如下配置，告诉IIS不要替换已生成的响应内容：

<system.webServer>
  <!-- 其他已有配置 -->
  <httpErrors existingResponse="PassThrough" />
</system.webServer>

方案2：手动构建JSON格式的401响应 #

不使用WebAPI自带的Unauthorized()方法，直接创建HttpResponseMessage并指定内容类型，确保响应不被IIS篡改：

var errorDto = new UnauthorizedError() {
    Id = 1,
    Error = Error.UserNotFound,
    Message = "User not found"
};
var response = Request.CreateResponse(HttpStatusCode.Unauthorized, errorDto);
response.Content.Headers.ContentType = new System.Net.Http.Headers.MediaTypeHeaderValue("application/json");
return response;

方案3：ASP.NET Core项目适配 #

如果是ASP.NET Core项目，可通过中间件自定义状态码处理逻辑，强制401响应返回JSON：

// 在Startup.cs的Configure方法中添加
app.UseStatusCodePages(async context =>
{
    var response = context.HttpContext.Response;
    if (response.StatusCode == StatusCodes.Status401Unauthorized)
    {
        response.ContentType = "application/json";
        var errorDto = new UnauthorizedError
        {
            Id = 1,
            Error = Error.UserNotFound,
            Message = "User not found"
        };
        await response.WriteAsJsonAsync(errorDto);
    }
});

内容的提问来源于stack exchange，提问作者Ivan-Mark Debono