RFC 9457 Problem Details Generator
By Dev Kraken · 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.
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 OKwith"status": 404in 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.
Related tools
All tools →-
chmod Calculator
Convert between octal (755) and symbolic (rwxr-xr-x) Linux & Unix file permissions — with a cheat-sheet for the values you actually use.
-
Crontab Generator
The quick, simple editor for cron schedule expressions — translate any crontab line into plain English and preview its next run times.
-
REST API Error Response Format Checker
Paste a JSON API error response to score its structure, spot missing fields, and generate a cleaner, more consistent error format — runs in your browser.
-
Cloudflare _headers Tester
Paste a Cloudflare Pages _headers file and a URL to see exactly which headers it gets — with line-by-line errors for the mistakes Cloudflare ignores silently.