RFC 9457 problem details give HTTP APIs one standard shape for error responses: a JSON object with type, title, status, detail and instance, served as application/problem+json. Clients stop guessing whether an error lives in error, message or errors[0].msg, and you stop inventing a new format for every service. This guide explains each member, how to design problem types, validation and rate-limit examples, complete handlers for Express and FastAPI, the built-in support in Spring Boot and ASP.NET Core, an OpenAPI schema, and how clients should read these responses.

RFC 9457 problem details response: an HTTP status code with an application/problem+json body containing type, title, status, detail, instance and extension members
A problem details response: the real HTTP status code plus a small, predictable JSON body that clients can branch on.

From my own work: On API projects I take over, error handling is usually the least consistent part: one route returns a string, another a nested object, a third an HTML error page from the proxy. Moving everything to problem details was mostly mechanical, and the biggest win was on the client side, where one small function replaced a pile of special cases.

What RFC 9457 problem details are

RFC 9457, published in July 2023, defines a problem details object for HTTP APIs and obsoletes RFC 7807. The core format is unchanged, so existing RFC 7807 responses remain valid. The new RFC clarifies how to handle multiple problems, recommends absolute type URIs, and created an IANA registry of common problem types (RFC 9457). Here is the shape:

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Content-Language: en

{
  "type": "https://api.example.com/problems/out-of-credit",
  "title": "You do not have enough credit.",
  "status": 403,
  "detail": "Your current balance is 30, but that costs 50.",
  "instance": "/account/12345/transactions/abc",
  "balance": 30,
  "accounts": ["/account/12345", "/account/67890"]
}

The five standard members are all optional, and anything else is an extension member, like balance above. Clients must ignore extensions they do not recognise, which lets a problem type gain fields later without breaking anyone.

Member Type Rule worth remembering
type URI reference The primary identifier clients branch on; assumed about:blank when missing
title String Short and the same for every occurrence of the type, except for translation
status Number Advisory copy of the HTTP status; the real response must use the same code
detail String This occurrence, written to help the client fix it; clients should not parse it
instance URI reference Identifies this occurrence, for example a request ID you can find in logs

Designing problem types

A problem type is a category of error that clients can act on, identified by its type URI. The RFC says a new type must document a type URI, a short title and the status code it is used with, and that the URI should resolve to human-readable documentation (RFC 9457, section 4). In practice:

  • Use absolute HTTPS URIs you control, such as https://api.example.com/problems/validation, and publish a short page at each one explaining the cause and the fix. Relative URIs resolve differently depending on the request path.
  • Do not create a type for every status code. When a plain status code says everything, such as 404 for an unknown resource, use about:blank with the standard reason phrase as the title.
  • Name extensions carefully. The RFC recommends names that start with a letter, use only letters, digits and underscores, and are at least three characters long, so they also work in the XML form.
  • Treat type URIs as a contract. Changing one is a breaking change for clients that branch on it, which tools like the oasdiff breaking change check can flag if the types appear in your OpenAPI file.

Before you invent a type, check the IANA HTTP Problem Types registry, which RFC 9457 created and which already lists types for some HTTP extensions (IANA: HTTP Problem Types).

Common error responses as problem details

Validation errors are the case that teams get wrong most often. RFC 9457 shows the pattern: one problem type for the request, with an errors extension listing each field and a JSON pointer to it.

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

{
  "type": "https://api.example.com/problems/validation",
  "title": "Your request is not valid.",
  "status": 422,
  "detail": "2 fields failed validation.",
  "instance": "urn:request:7f3c2a91-0b6e-4c8e-9d1a-2b5f8e4c6d10",
  "errors": [
    { "pointer": "#/email", "detail": "must be a valid email address" },
    { "pointer": "#/age",   "detail": "must be a positive integer" }
  ]
}
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 30

{
  "type": "https://api.example.com/problems/rate-limited",
  "title": "Too many requests.",
  "status": 429,
  "detail": "Limit of 100 requests per minute exceeded. Retry in 30 seconds."
}

Status codes still carry the main meaning, so pick them first and the problem type second:

Situation Status Problem type
Malformed JSON body 400 about:blank or /problems/malformed-body
Missing or invalid credentials 401 about:blank, plus WWW-Authenticate
Authenticated but not allowed 403 about:blank or a specific business rule type
Resource not found 404 about:blank
Version conflict or duplicate 409 /problems/conflict
Field validation failed 422 /problems/validation with errors
Rate limit exceeded 429 /problems/rate-limited, plus Retry-After
Unexpected server failure 500 about:blank with only an instance ID

Conflicts often come from retries and concurrent writes; the idempotency keys guide shows how to return a consistent 409, and the API rate limiting guide covers where the 429 values come from.

RFC 9457 problem details in Node.js with Express

Define one error class, throw it from routes, and let a single error middleware turn everything into problem details. Unknown errors become a generic 500 with only a request ID, so stack traces never reach the client.

// problem.js
import { randomUUID } from 'node:crypto';

const BASE = 'https://api.example.com/problems/';

export class Problem extends Error {
  constructor(status, { type, title, detail, ...extensions } = {}) {
    super(detail || title);
    this.status = status;
    this.type = type ? BASE + type : 'about:blank';
    this.title = title;
    this.detail = detail;
    this.extensions = extensions;
  }
}

export function problemHandler(err, req, res, next) {
  if (res.headersSent) return next(err);
  const id = req.id || randomUUID();

  // Body parser errors: invalid JSON
  if (err.type === 'entity.parse.failed') {
    err = new Problem(400, { title: 'Bad Request', detail: 'The request body is not valid JSON.' });
  }

  const known = err instanceof Problem;
  if (!known) console.error({ id, err });          // full detail stays in your logs

  const status = known ? err.status : 500;
  const body = known
    ? { type: err.type, title: err.title, status, detail: err.detail, ...err.extensions }
    : { type: 'about:blank', title: 'Internal Server Error', status };
  body.instance = `urn:request:${id}`;

  res.status(status).type('application/problem+json').json(body);
}
// app.js
import express from 'express';
import { Problem, problemHandler } from './problem.js';

const app = express();
app.use(express.json());

app.post('/users', (req, res) => {
  const errors = [];
  if (!/^[^@s]+@[^@s]+$/.test(req.body?.email ?? '')) {
    errors.push({ pointer: '#/email', detail: 'must be a valid email address' });
  }
  if (!Number.isInteger(req.body?.age) || req.body.age < 1) {
    errors.push({ pointer: '#/age', detail: 'must be a positive integer' });
  }
  if (errors.length) {
    throw new Problem(422, {
      type: 'validation',
      title: 'Your request is not valid.',
      detail: `${errors.length} field(s) failed validation.`,
      errors,
    });
  }
  res.status(201).json({ ok: true });
});

app.use((req, res) => {
  throw new Problem(404, { title: 'Not Found', detail: `No route for ${req.method} ${req.path}.` });
});
app.use(problemHandler);
app.listen(3000);

Express 5 forwards errors thrown in async handlers to the error middleware automatically; on Express 4, wrap async routes or call next(err).

Problem details in Python with FastAPI

FastAPI’s default errors use a detail field with its own structure. Register three exception handlers to replace them: your own problems, HTTP errors, and request validation errors.

# main.py
import logging, uuid
from fastapi import FastAPI, Request
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from starlette.exceptions import HTTPException as StarletteHTTPException
from http import HTTPStatus

BASE = "https://api.example.com/problems/"
MEDIA = "application/problem+json"
app = FastAPI()

class Problem(Exception):
    def __init__(self, status: int, type: str | None = None, title: str | None = None,
                 detail: str | None = None, **extensions):
        self.status, self.detail, self.extensions = status, detail, extensions
        self.type = BASE + type if type else "about:blank"
        self.title = title or HTTPStatus(status).phrase

def problem_response(status, body):
    body.setdefault("status", status)
    body["instance"] = f"urn:request:{uuid.uuid4()}"
    return JSONResponse(body, status_code=status, media_type=MEDIA)

@app.exception_handler(Problem)
async def handle_problem(request: Request, exc: Problem):
    return problem_response(exc.status, {"type": exc.type, "title": exc.title,
                                         "detail": exc.detail, **exc.extensions})

@app.exception_handler(StarletteHTTPException)
async def handle_http(request: Request, exc: StarletteHTTPException):
    return problem_response(exc.status_code, {"type": "about:blank",
                            "title": HTTPStatus(exc.status_code).phrase, "detail": str(exc.detail)})

@app.exception_handler(RequestValidationError)
async def handle_validation(request: Request, exc: RequestValidationError):
    errors = [{"pointer": "#/" + "/".join(str(p) for p in e["loc"][1:]), "detail": e["msg"]}
              for e in exc.errors()]
    return problem_response(422, {"type": BASE + "validation", "title": "Your request is not valid.",
                                  "detail": f"{len(errors)} field(s) failed validation.", "errors": errors})

@app.exception_handler(Exception)
async def handle_unexpected(request: Request, exc: Exception):
    logging.exception("unhandled error")
    return problem_response(500, {"type": "about:blank", "title": "Internal Server Error"})

Built-in support: Spring Boot and ASP.NET Core

Some frameworks already speak problem details, so use their support instead of writing your own:

  • Spring Framework 6 and Spring Boot 3 or later provide a ProblemDetail class and the ErrorResponse contract. Throw an ErrorResponseException or return ProblemDetail from a @ExceptionHandler, and extend ResponseEntityExceptionHandler to convert Spring MVC’s own exceptions. In Spring Boot, the property spring.mvc.problemdetails.enabled=true turns this on for built-in errors (Spring: error responses).
  • ASP.NET Core registers a problem details service with builder.Services.AddProblemDetails(); combined with app.UseExceptionHandler() and app.UseStatusCodePages(), unhandled exceptions and empty error responses get problem details bodies, and Results.Problem and Results.ValidationProblem create them explicitly (Microsoft Learn: handle errors in APIs).
// ASP.NET Core minimal API
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddProblemDetails();
var app = builder.Build();
app.UseExceptionHandler();
app.UseStatusCodePages();

app.MapGet("/orders/{id:int}", (int id) =>
    id == 42 ? Results.Ok(new { id })
             : Results.Problem(statusCode: 404, title: "Not Found",
                               detail: $"Order {id} does not exist."));
app.Run();

Document problem details in OpenAPI

Describe the schema once and reference it from every error response, so client generators and reviewers see the contract:

components:
  schemas:
    Problem:
      type: object
      properties:
        type:     { type: string, format: uri-reference, default: about:blank }
        title:    { type: string }
        status:   { type: integer, minimum: 100, maximum: 599 }
        detail:   { type: string }
        instance: { type: string, format: uri-reference }
      additionalProperties: true
    ValidationProblem:
      allOf:
        - $ref: '#/components/schemas/Problem'
        - type: object
          properties:
            errors:
              type: array
              items:
                type: object
                required: [pointer, detail]
                properties:
                  pointer: { type: string }
                  detail:  { type: string }
  responses:
    ValidationFailed:
      description: The request body failed validation.
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/ValidationProblem' }

Reading problem details in clients

Clients should branch on the status code and the type, show detail to people, and never parse detail for data. Remember that a proxy or CDN can still return HTML errors, so check the content type before parsing.

// api.ts
export class ApiProblem extends Error {
  constructor(public status: number, public problem: Record<string, any>) {
    super(problem.detail || problem.title || `HTTP ${status}`);
  }
  get type(): string { return this.problem.type ?? 'about:blank'; }
}

export async function api(path: string, init?: RequestInit) {
  const res = await fetch(path, {
    ...init,
    headers: { Accept: 'application/json, application/problem+json', ...init?.headers },
  });
  if (res.ok) return res.status === 204 ? null : res.json();
  const ct = res.headers.get('content-type') ?? '';
  const problem = ct.includes('json') ? await res.json() : { title: res.statusText };
  throw new ApiProblem(res.status, problem);
}

// usage
try { await api('/users', { method: 'POST', body: JSON.stringify(form) }); }
catch (e) {
  if (e instanceof ApiProblem && e.type.endsWith('/problems/validation')) {
    for (const err of e.problem.errors) showFieldError(err.pointer.slice(2), err.detail);
  } else throw e;
}

What never goes in a problem details response

The RFC’s security section warns against exposing implementation internals, such as stack dumps, through problem details (RFC 9457, security considerations). Keep SQL errors, file paths, framework names, internal hostnames and personal data in your logs, linked by the instance ID. The same discipline applies to signed callbacks, as in the webhook signature verification guide: a verification failure should say that it failed, not why the signature differed.

RFC 9457 checklist

  • Every error response uses application/problem+json, including 404 and 500.
  • The status member always equals the real HTTP status.
  • Absolute HTTPS type URIs, each with a documentation page.
  • about:blank for errors a status code already explains.
  • Validation errors in one errors array with JSON pointers.
  • An instance ID that maps to your logs; no stack traces or internals.
  • A shared Problem schema referenced from every error in OpenAPI.
  • Clients branch on status and type, never on detail text.

Want this done on your own server or site?

I am Saizul Amin, a web developer and technical SEO consultant. I set up and harden VPS servers, migrate WordPress sites, fix indexing problems and build automations. See my portfolio or get in touch.

FAQ

What is RFC 9457?

RFC 9457 is the IETF standard for problem details in HTTP APIs. It defines a JSON object, served as application/problem+json, with type, title, status, detail and instance members, plus extension members for problem-specific data. It replaced RFC 7807 in 2023.

What is the difference between RFC 7807 and RFC 9457?

The format is the same, so RFC 7807 responses are still valid. RFC 9457 clarifies how to report multiple problems, recommends absolute type URIs, and created an IANA registry for common problem types.

Which fields are required in a problem details response?

None are strictly required. In practice include type, title and status on every response, detail when it helps the client fix the problem, and instance so support teams can find the matching log entry.

How should I return validation errors with problem details?

Use one problem type such as a validation type with status 400 or 422, and add an errors extension array in which each item has a JSON pointer to the field and a detail message.

Should the HTTP status code and the status member match?

Yes. The specification says generators must use the same status code in the actual HTTP response. The member is only an advisory copy for logs and for clients that receive the body without its headers.

Sources

NEW BLOGS. REAL STRATEGIES. REAL RESULTS.

Join our community and receive powerful SEO tips, web optimization guides, and growth strategies as soon as they’re published.

Don’t just read blogs — stay ahead of the competition.

We don’t spam! Read our privacy policy for more info.

Share.
Leave A Reply