RFC 9457 Problem Details Generator

By · Updated

Choose what went wrong to get the right HTTP status and a spec-checked application/problem+json body, or paste your own to validate it against RFC 9457. Then copy the raw response or server code for Express, Next.js, FastAPI, or Spring Boot.

Problem details builder and validator

The JSON parsed but broke business rules. Use 400 only when the body can't be parsed at all.

Spec check Valid RFC 9457

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

{
  "type": "https://api.example.com/problems/validation-error",
  "title": "Your request is not valid",
  "status": 422,
  "detail": "2 fields failed validation.",
  "instance": "/orders/ord_8f3c",
  "errors": [
    {
      "pointer": "#/email",
      "detail": "must be a valid email address"
    },
    {
      "pointer": "#/age",
      "detail": "must be a positive integer"
    }
  ]
}

Which HTTP status code should an API error use?

The scenarios above, with the reasoning behind each status. Click a row to load it into the generator.

Situation Status Why
422 The JSON parsed but broke business rules. Use 400 only when the body can't be parsed at all.
400 The server couldn't read the request, so nothing about it can be validated yet.
401 401 means "who are you?" and MUST carry a WWW-Authenticate header (RFC 9110 §15.5.2).
403 The caller is known but lacks permission. Re-authenticating won't help, so it isn't 401.
404 Nothing beyond the status code to explain, so about:blank with the standard reason phrase is enough.
409 The request is valid on its own but collides with existing data. Retrying the same request will fail again.
412 A conditional request header didn't match. Use 409 only for conflicts that don't come from If-* headers.
413 The body exceeds a size limit. Include the limit so clients can check before uploading.
415 The format is the problem, not the content, so it isn't 400 or 422.
429 Tell the client when to come back with Retry-After, and mirror it in the body for logging.
403 The RFC's own example: a domain-specific problem type with extension members the client can act on.
500 Never put stack traces in detail (§5). Return a trace ID and keep the internals in your logs.
503 Temporary by definition, so pair it with Retry-After. Use 500 when there's no recovery time to share.

The five standard members

All five are optional. A member with the wrong JSON type must be ignored by clients, which is why the validator treats type mismatches as errors.

Member JSON type Rules
type string (URI reference) Primary identifier of the problem type. Defaults to "about:blank". Absolute URIs are recommended, ideally pointing at human-readable docs.
title string Short summary of the problem type. Should not change between occurrences, except for localization.
status number The HTTP status code. Advisory, but it MUST match the actual response status.
detail string Explanation of this occurrence, written to help the client fix it. Not for debugging data, and clients shouldn't parse it.
instance string (URI reference) Identifies this specific occurrence, such as a request or log URL.

Anything else is an extension member: names should start with a letter, use only letters, digits, and underscores, and be at least three characters long, as in errors or trace_id.

Mistakes the validator catches

  • status disagrees with the response. Returning 200 OK with "status": 404 in the body breaks caches, monitoring, and every client that checks the status line first.
  • status as a string. "status": "422" has the wrong JSON type, so spec-following clients ignore it entirely.
  • A custom title with about:blank. Without a type URI, the title should be the plain reason phrase. Custom wording belongs to a problem type you define and document.
  • Stack traces in detail. The RFC says problem details are not a debugging tool. Return a trace ID and keep the exception in your logs.
  • Served as application/json. It parses, but gateways and clients can't tell it's a problem details object without reading it.

Go deeper

Frequently asked

What is RFC 9457?
RFC 9457, "Problem Details for HTTP APIs", is the IETF standard for machine-readable error responses. It defines a JSON object served as application/problem+json with five optional members (type, title, status, detail, and instance) plus any extension members your API needs. Published in July 2023, it replaces RFC 7807 with the same format and clarifications on multiple problems, type URIs, and a shared registry of problem types.
What changed from RFC 7807 to RFC 9457?
The wire format is the same, so an RFC 7807 response is a valid RFC 9457 response. RFC 9457 clarifies how to handle several problems in one response (report the most relevant one), recommends absolute type URIs and resolvable documentation, creates an IANA registry for common problem types, and adds guidance on extension member names. You can switch the reference in your docs without changing code.
Which members are required in a problem details object?
None. Every member is optional, and an empty object is technically valid. In practice, send at least type (or rely on about:blank), title, status, and detail. Note that status MUST equal the HTTP status of the response it's in, and a member with the wrong JSON type, such as status as a string, must be ignored by clients.
What does type: about:blank mean?
It means the problem has no meaning beyond the HTTP status code. It's the default when type is missing. With about:blank, title SHOULD be the standard reason phrase for the status (for example "Not Found" for 404). If you want a custom title or extension members, define your own problem type URI instead.
Should I return 400 or 422 for validation errors?
Return 400 when the server can't parse the request at all, such as malformed JSON or a wrong structure. Return 422 Unprocessable Content when the request parses fine but breaks a rule, such as an invalid email or an age below zero. List the individual field errors in an extension member like errors, with a JSON Pointer to each field.
What Content-Type should a problem details response use?
application/problem+json (or application/problem+xml for the XML form). Clients and API gateways use the media type to recognise an error body without parsing it. Plain application/json still works, but it hides the fact that the body follows RFC 9457.
Can I add my own fields to a problem details response?
Yes. These are extension members, and clients must ignore any they don't recognise. The RFC recommends names that start with a letter, contain only letters, digits, and underscores, and are at least three characters long, so trace_id or errors rather than id or error-list. Don't use them to expose stack traces or other internals.
Does this tool send my error payloads anywhere?
No. Generation and validation run as JavaScript in your browser. Nothing is uploaded or logged, so you can paste real production error bodies.
All tools →