Skip to content
MINH VO A working notebook
by an engineer in Vietnam
Foundation7 min read

Design a consistent API error with Problem Details

Use RFC 9457 Problem Details for stable API errors, with field-level validation data, safe diagnostics and client behavior that survives wording changes.

Olive and charcoal server components connected on a warm beige background

Problem Details gives an HTTP API a standard shape for an error response. If you are building a client and server together, use it to separate the machine-readable error identity from the sentence shown to a person. The type identifies the problem, while title and detail explain it at different levels of specificity.

RFC 9457 defines the format and the application/problem+json media type. It does not prescribe a universal catalog of business errors. You still need to decide which failures deserve distinct identities and what information the caller is allowed to receive.

Begin with a failure the client must repair

Consider a hypothetical checkout form that submits an invalid quantity and an unsupported delivery option. The request is valid JSON, but its instructions cannot be processed under the API’s validation rules. A response could look like this:

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://shop.example/problems/invalid-order",
  "title": "Order validation failed",
  "status": 422,
  "detail": "Correct the highlighted fields and submit the order again.",
  "instance": "urn:request:checkout-418",
  "errors": [
    {"pointer":"/items/0/quantity","code":"positive_integer_required"},
    {"pointer":"/delivery/method","code":"unsupported_delivery_method"}
  ]
}

The example URL and request identifier are illustrative. The errors member is an extension designed for this API. Its pointer and code fields are not built-in Problem Details members, so document their meaning, escaping rules and stability guarantees.

The client can associate /items/0/quantity with the first line item’s quantity input. It can translate positive_integer_required into its own language without parsing the English detail string. If the form changes, a general error area should still show a useful response when a pointer has no matching visible field.

Choose stable types with narrow meanings

A problem type should describe a condition whose interpretation remains stable. invalid-order can represent a documented validation failure family. something-went-wrong-v2 gives clients little information and tends to accumulate unrelated behavior.

RFC 9457 uses a URI reference for type. An HTTP URL is useful when it resolves to documentation, although clients should not need to fetch that page synchronously to handle an error. A documentation outage should not stop checkout from displaying a validation message. Resolve and cache documentation separately if a development tool wants to display it.

The standard’s about:blank type means that the problem has no additional semantics beyond the HTTP status. That can be appropriate for a generic error. If the client needs to distinguish an expired invitation from a used invitation, a specific type or documented extension provides more useful behavior.

A title is a short description of the problem type and normally remains the same across instances, apart from localization. The detail explains this occurrence. Do not move a transaction-specific identifier into the title and make every error look like a new class.

One HTTP error split into transport status, stable problem identity, human explanation and field-specific extension dataView full-size image ↗

Each layer has a different consumer. Generic HTTP software sees the status and media type. The application reads the problem identity and extension fields. A person receives a useful explanation that does not expose the server’s internals.

Keep the status line and body consistent

The body’s status member records the HTTP status associated with the problem. Intermediaries sometimes change a response’s status, so the field can preserve useful context. In your own server, generate the status line and body value from one mapping. Returning HTTP 200 with status: 422 inside the JSON weakens monitoring, caching and generic client behavior.

The choice between 400 and 422 for a particular validation failure belongs to the broader API contract. RFC 9110 defines the status semantics. Problem Details does not override those definitions or make a domain-specific choice for you.

Clients should also tolerate extension members they do not understand. Adding a diagnostic link should not crash an otherwise compatible client. That tolerance does not mean accepting arbitrary types for known fields. If errors is documented as an array, the consumer should handle a malformed response safely rather than assume every member can be rendered directly as HTML.

Separate useful diagnostics from private internals

A database stack trace is usually a poor detail. It can expose table names, internal file paths and implementation details while giving the caller no repair action. Map a recognized uniqueness failure to the relevant business problem. Log the internal exception in a restricted system and use a correlation identifier to connect the public response to that record.

The correlation identifier itself needs a policy. Avoid embedding an access token, email address or full request URL with sensitive query parameters. If instance is a retrievable URL, control who can retrieve its contents. Possessing the problem response should not grant access to another tenant’s diagnostic page.

For security-sensitive operations, consider whether detailed failures disclose account or resource existence. A password-reset endpoint may intentionally return the same public result for known and unknown addresses. A standard JSON envelope cannot compensate for a revealing error catalog.

Map internal failures at one controlled boundary

A useful error mapper starts from an allowed public catalog. Suppose an account update violates the known uniqueness rule for a display slug. The mapper can return a stable slug-conflict problem with a field pointer. An unfamiliar database exception should follow a generic internal-error path until the service has a reviewed mapping for it. Treating every database exception as a duplicate slug gives the user a false diagnosis when the actual cause is a disconnected database.

const publicProblems = {
  slug_conflict: {
    status: 409,
    type: 'https://shop.example/problems/slug-conflict',
    title: 'This profile address is already in use'
  }
};

function publicProblem(code, requestId) {
  const known = Object.hasOwn(publicProblems, code) ? publicProblems[code] : undefined;
  if (!known) {
    return { status: 500, type: 'about:blank',
      title: 'Internal Server Error', instance: 'urn:request:' + requestId };
  }
  return { ...known, instance: 'urn:request:' + requestId };
}

The code accepts an internal classification and a safe request identifier; it deliberately does not accept a raw exception message to copy into the response. In a real handler, produce the classification only after recognizing the specific failure. Validate the request identifier’s format before using it in a URI, and keep the full exception in a restricted diagnostic record correlated through that identifier.

A recognized internal failure maps to an allowed public problem, while an unknown exception maps to a generic 500; detailed diagnostics remain in a restricted logView full-size image ↗

Zalando’s RESTful API guidelines provide an example of a company using a common problem representation across services. Such guidance can help keep clients consistent, while RFC 9457 supplies the normative format used here. Check the current version of a company’s guidelines before copying historical RFC references or organization-specific field conventions.

Changing an error contract can break clients even when the normal success response is unchanged. Renaming errors to violations, changing a pointer syntax or reusing an existing type for a different condition can disrupt form recovery. Keep type meanings stable, make additive extensions tolerable and version incompatible behavior deliberately.

Localization is another reason to preserve the machine contract. A Vietnamese detail and an English detail can describe the same problem type. The language of the explanation should not change how the client identifies a duplicate slug or attaches an error to a field. Test both localized messages against the same recovery behavior while checking that the rendered text remains escaped.

Test unknown errors and partial understanding

Test a recognized validation problem, an unknown problem type and a non-JSON failure from a proxy. The client needs a useful fallback for all three. An upstream HTML error should not become a JSON parsing exception that hides the original failure from the user.

On the server, test that each mapped error keeps the expected status and stable type while excluding private exception content. Also test field errors with an empty list, an unexpected pointer and multiple failures on one input. Those cases expose assumptions in form rendering.

Keep the first implementation small: one mapper for public error types, one documented extension shape for field validation and one fallback for unexpected exceptions. Add more problem types when a client has a distinct recovery action. That keeps the catalog tied to actual behavior instead of every exception class in the codebase.

Sources & further reading

  1. RFC 9457, Problem details for HTTP APIs
  2. RFC 9110, HTTP semantics
  3. Zalando RESTful API guidelines
← Back to the journal
All notes

Illustration

100%