How to read problem details JSON with HttpClient in C#

These error responses typically contain a status code (e.g., 400 for "Bad Request") along with a body that looks something like this:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Invalid input.",
  "status": 400,
  "traceId": "abc123xyz",
  "errors": {
    "Quantity": [
      "Quantity must be between 1 and 100."
    ]
  }
}

This structure is often used to communicate error details in a machine-readable format.

Request to API using HttpClient

Here’s an example of making a POST request to an API, checking the response's Content-Type header to confirm it matches the application/problem+json format, and then reading the response body into a string:

var response = await httpClient.PostAsync(requestUrl, jsonContent);

if (!response.IsSuccessStatusCode && 
    response.Content.Headers.ContentType?.MediaType == "application/problem+json")
{
    var problemDetailsJson = await response.Content.ReadAsStringAsync();
    
    // Process the error details
}

Note: The null-conditional operator (?.) is used here to safely check if the Content-Type header is available.

Handling Error Details

There are several ways you can handle and use the problem details:

• Log the error details.
• Display the error to the user.
• Deserialize the JSON to extract specific information and handle it programmatically (e.g., retrying a request based on specific errors).

Custom Problem Details Class

To deserialize the problem details JSON, you may define a class that represents the structure of the error response.

public class CustomProblemDetails
{
    public string Type { get; set; }
    public string Title { get; set; }
    public int Status { get; set; }
    public string TraceId { get; set; }
    public Dictionary<string, string[]> Errors { get; set; }
}

Deserializing JSON with System.Text.Json

You can use the built-in System.Text.Json library to deserialize the problem details JSON.

using System.Text.Json;

var response = await httpClient.PostAsync(requestUrl, jsonContent);

if (!response.IsSuccessStatusCode && 
    response.Content.Headers.ContentType?.MediaType == "application/problem+json")
{
    var json = await response.Content.ReadAsStringAsync();
    var jsonOptions = new JsonSerializerOptions(JsonSerializerDefaults.Web);
    
    var problemDetails = JsonSerializer.Deserialize<CustomProblemDetails>(json, jsonOptions);
    Console.WriteLine($"There are {problemDetails.Errors?.Count} error(s).");
}

Output:

There are 1 error(s).

Deserializing JSON with Newtonsoft

Alternatively, you can use Newtonsoft.Json to deserialize the problem details:

using Newtonsoft.Json;

var response = await httpClient.PostAsync(requestUrl, jsonContent);

if (!response.IsSuccessStatusCode && 
    response.Content.Headers.ContentType?.MediaType == "application/problem+json")
{
    var json = await response.Content.ReadAsStringAsync();
    var problemDetails = JsonConvert.DeserializeObject<CustomProblemDetails>(json);

    Console.WriteLine($"There are {problemDetails.Errors?.Count} error(s).");
}

Output:

There are 1 error(s).

Handling Additional Error Information

In some cases, the problem details may include extra properties beyond the standard fields.

For example, an API might return the following error response:

{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "Invalid input.",
    "status": 400,
    "traceId": "abc123xyz",
    "errors": {
        "Quantity": [
            "Quantity must be between 1 and 100."
        ]
    },
    "internalErrorCode": 2001
}

To handle this extra information, you have two options:

Option 1: Subclass Your Problem Details Class

You can extend your custom class to include the additional properties:

public class ExtendedProblemDetails : CustomProblemDetails
{
    public int InternalErrorCode { get; set; }
}

Then deserialize the JSON into this extended class:

var jsonOptions = new JsonSerializerOptions(JsonSerializerDefaults.Web);
var problemDetails = JsonSerializer.Deserialize<ExtendedProblemDetails>(json, jsonOptions);
Console.WriteLine($"Internal error code: {problemDetails.InternalErrorCode}");

Output:

Internal error code: 2001

Option 2: Use [JsonExtensionData] Attribute

Alternatively, you can use the [JsonExtensionData] attribute to capture any additional properties in a dictionary:

using System.Text.Json.Serialization;

public class CustomProblemDetails
{
    public string Type { get; set; }
    public string Title { get; set; }
    public int Status { get; set; }
    public string TraceId { get; set; }
    public Dictionary<string, string[]> Errors { get; set; }

    [JsonExtensionData]
    public Dictionary<string, object> ExtensionData { get; set; }
}

Now, when you deserialize the JSON, you can retrieve the extra properties from the ExtensionData dictionary:

var jsonOptions = new JsonSerializerOptions(JsonSerializerDefaults.Web);
var problemDetails = JsonSerializer.Deserialize<CustomProblemDetails>(json, jsonOptions);

if (problemDetails.ExtensionData.TryGetValue("internalErrorCode", out object internalErrorCode))
{
    Console.WriteLine($"Internal error code from extension data: {internalErrorCode}");
}

Output:

Internal error code from extension data: 2001

Why Not Use the Built-in ProblemDetails Class?

While ASP.NET Core has built-in ProblemDetails and ValidationProblemDetails classes, you might want to create your own custom class for a few reasons:

1. Deserialization Issues: You may encounter issues when trying to deserialize the built-in classes, depending on your use case.
2. Avoiding Dependencies: By creating your own class, you avoid the dependency on the Microsoft.AspNetCore.Mvc package.

By following these examples, you can effectively handle standardized API error responses and process them based on your needs.