A Consistent Error Format

Every endpoint fails. If each one fails in its own format, a client has to write a separate error handler for each, and a handler written before your newest endpoint existed will not understand it.

One shape, used everywhere, turns that into a single piece of code on the client: read the status, read the machine-readable code, show the message, attach any field errors to the form. A new endpoint needs no new client work, which is the whole return on the effort.

There is a standard shape for this, so you do not have to invent one. Problem Details is an IETF specification — originally RFC 7807, now RFC 9457 — that defines a JSON document with a small set of known members: type, title, status, detail and instance. ASP.NET Core has first-class support for it, which is why validation failures already come back in that form.

The specification also allows extension members, and that is where your own fields go: a stable error code, a field errors object, a trace identifier. You get an agreed baseline that tooling understands, plus the parts specific to your API.

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{ "type": "https://errors.example.com/validation_failed",
  "title": "One or more fields are invalid.",
  "status": 400,
  "instance": "/api/employees",
  "code": "validation_failed",
  "traceId": "0HN7A1M4K2P9Q",
  "errors": { "email": ["Email is required."] } }

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{ "type": "https://errors.example.com/email_in_use",
  "title": "An employee already exists with that email address.",
  "status": 409,
  "instance": "/api/employees",
  "code": "email_in_use",
  "traceId": "0HN7A1M4K2P9R" }

HTTP/1.1 500 Internal Server Error
Content-Type: application/problem+json

{ "type": "https://errors.example.com/internal_error",
  "title": "The request could not be completed.",
  "status": 500,
  "instance": "/api/orders/1042",
  "code": "internal_error",
  "traceId": "0HN7A1M4K2P9S" }

• The content type is application/problem+json rather than application/json. That is part of the specification, and it lets a client recognise a problem document without inspecting the body.
• The members are the same in all three. A client reads code and traceId from every error response without asking which endpoint produced it.
• code is the part a client branches on. It is stable, lowercase and never translated, so "email_in_use" can be handled specifically while the human text is free to change.
• title is for a person. Rewording it is not a breaking change, which is exactly why clients must not compare against it.
• errors appears only where there are field errors. Optional members are a better contract than members that are always present and usually empty.
• The 500 says nothing about what broke. The traceId is how support connects this response to the log entry that does.

public static class ApiError
{
    public static IResult Create(
        int status,
        string code,
        string message,
        HttpContext http,
        IDictionary<string, string[]>? fieldErrors = null)
    {
        var problem = new ProblemDetails
        {
            Status = status,
            Title = message,
            Type = $"https://errors.example.com/{code}",
            Instance = http.Request.Path
        };

        problem.Extensions["code"] = code;
        problem.Extensions["traceId"] = http.TraceIdentifier;

        if (fieldErrors is not null)
        {
            problem.Extensions["errors"] = fieldErrors;
        }

        return Results.Problem(problem);
    }
}

// At the call site
return ApiError.Create(
    StatusCodes.Status409Conflict,
    "email_in_use",
    "An employee already exists with that email address.",
    http);

• One helper is what makes the shape real. A documented convention that each endpoint implements by hand drifts within a month; a helper is the path of least resistance.
• ProblemDetails.Extensions holds the members the specification does not define. They appear as ordinary top-level properties in the JSON.
• TraceIdentifier is per request and already appears in the framework's logs, so quoting it in a support ticket leads straight to the right entry.
• Instance records which path produced the error, which matters when a client is calling several endpoints and reporting one failure.
• Unhandled exceptions need the same treatment, through app.UseExceptionHandler and a handler that maps the exception to this shape. Without that, one unexpected failure returns something no client recognises.