JSON API Error Handling: RFC 9457 Problem Details and Error Response Formats

Written and reviewed by the Jsonic editorial team — every guide is verified against the official spec or runtime before publication.

Last updated: May 19, 2026

Poorly designed JSON error responses are one of the most common API usability problems. When your API returns a cryptic {"error": true} or an HTML 500 page instead of structured JSON, every client developer has to guess what went wrong. RFC 9457 Problem Details provides a standard, machine-readable format that makes errors self-describing, consistent, and safe. This guide covers the standard, HTTP status codes, validation patterns, and security best practices for Node.js and Python APIs.

RFC 9457 Problem Details — The IETF Standard

RFC 9457 (published August 2023, replacing RFC 7807) defines a JSON format for HTTP error responses with a application/problem+json Content-Type. The format is extensible: add any fields your API needs beyond the base five.

{
  "type": "https://api.example.com/errors/validation-failed",
  "title": "Validation Failed",
  "status": 422,
  "detail": "The submitted data is invalid. See 'errors' for field-level details.",
  "instance": "/requests/f3fc8e22-a8e5-4c1e-9e1a-83a4d5b3a456",
  "errors": [
    {
      "field": "email",
      "message": "Must be a valid email address",
      "code": "invalid_format"
    },
    {
      "field": "age",
      "message": "Must be at least 18",
      "code": "min_value",
      "meta": { "minimum": 18, "actual": 15 }
    }
  ]
}

HTTP Status Codes for JSON APIs

Use 400 for malformed syntax, 422 for valid JSON that fails business validation. Never return 200 with an error body — clients check the status code first.

Node.js / Express Error Response Patterns

// Problem Details factory
interface ProblemDetail {
  type: string
  title: string
  status: number
  detail?: string
  instance?: string
  [key: string]: unknown  // extension members
}

function problemDetail(
  status: number,
  title: string,
  detail?: string,
  extensions?: Record<string, unknown>
): ProblemDetail {
  return {
    type: `https://api.example.com/errors/${title.toLowerCase().replace(/\s+/g, '-')}`,
    title,
    status,
    ...(detail ? { detail } : {}),
    ...extensions,
  }
}

// Express error middleware
app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
  console.error(err)

  if (err.name === 'ValidationError') {
    return res.status(422)
      .type('application/problem+json')
      .json(problemDetail(422, 'Validation Failed', err.message, {
        errors: (err as any).errors,
      }))
  }

  if (err.name === 'NotFoundError') {
    return res.status(404)
      .type('application/problem+json')
      .json(problemDetail(404, 'Not Found', err.message, {
        instance: req.path,
      }))
  }

  // Generic 500 — never expose internal details
  res.status(500)
    .type('application/problem+json')
    .json(problemDetail(500, 'Internal Server Error', 'An unexpected error occurred.'))
})

Validation Error Response Format

// Zod validation errors → RFC 9457
import { z } from 'zod'

const UserCreateSchema = z.object({
  name: z.string().min(1, 'Name is required'),
  email: z.string().email('Invalid email format'),
  age: z.number().int().min(18, 'Must be at least 18'),
})

app.post('/users', (req, res) => {
  const result = UserCreateSchema.safeParse(req.body)
  if (!result.success) {
    const errors = result.error.issues.map(issue => ({
      field: issue.path.join('.'),
      message: issue.message,
      code: issue.code,
    }))

    return res.status(422)
      .type('application/problem+json')
      .json({
        type: 'https://api.example.com/errors/validation-failed',
        title: 'Validation Failed',
        status: 422,
        detail: `${errors.length} validation error(s). See 'errors' for details.`,
        errors,
      })
  }
  // ... create user
})

// Example 422 response:
// {
//   "type": "https://api.example.com/errors/validation-failed",
//   "title": "Validation Failed",
//   "status": 422,
//   "detail": "2 validation error(s). See 'errors' for details.",
//   "errors": [
//     {"field": "email", "message": "Invalid email format", "code": "invalid_string"},
//     {"field": "age", "message": "Must be at least 18", "code": "too_small"}
//   ]
// }

Python / FastAPI Error Patterns

from fastapi import FastAPI, Request, HTTPException
from fastapi.responses import JSONResponse
from fastapi.exception_handlers import http_exception_handler
import traceback

app = FastAPI()

class ProblemDetail(BaseModel):
    type: str
    title: str
    status: int
    detail: str | None = None
    instance: str | None = None

# Custom exception
class NotFoundError(Exception):
    def __init__(self, resource: str, id: int):
        self.resource = resource
        self.id = id

@app.exception_handler(NotFoundError)
async def not_found_handler(request: Request, exc: NotFoundError):
    return JSONResponse(
        status_code=404,
        media_type='application/problem+json',
        content={
            'type': 'https://api.example.com/errors/not-found',
            'title': 'Not Found',
            'status': 404,
            'detail': f'{exc.resource} with id {exc.id} was not found.',
            'instance': str(request.url),
        }
    )

# FastAPI validation errors (422) are already RFC 7807-style
# But you can customize with:
@app.exception_handler(RequestValidationError)
async def validation_error_handler(request: Request, exc: RequestValidationError):
    errors = [
        {'field': '.'.join(str(loc) for loc in error['loc'][1:]),
         'message': error['msg'],
         'code': error['type']}
        for error in exc.errors()
    ]
    return JSONResponse(
        status_code=422,
        media_type='application/problem+json',
        content={
            'type': 'https://api.example.com/errors/validation-failed',
            'title': 'Validation Failed',
            'status': 422,
            'errors': errors,
        }
    )

Client-Side Error Handling

// Typed error handling for API clients
interface ApiError {
  type: string
  title: string
  status: number
  detail?: string
  errors?: Array<{ field: string; message: string; code: string }>
}

function isApiError(body: unknown): body is ApiError {
  return typeof body === 'object' && body !== null && 'status' in body && 'title' in body
}

async function apiRequest<T>(url: string, init?: RequestInit): Promise<T> {
  const res = await fetch(url, {
    headers: { 'Content-Type': 'application/json', Accept: 'application/json', ...init?.headers },
    ...init,
  })
  const body = await res.json().catch(() => null)

  if (!res.ok) {
    if (isApiError(body)) {
      // Show field-level errors to user
      if (body.status === 422 && body.errors) {
        throw new ValidationError(body.errors)
      }
      throw new ApiError(body.status, body.title, body.detail)
    }
    throw new Error(`HTTP ${res.status}: ${res.statusText}`)
  }
  return body as T
}

// React error display
function FieldErrors({ errors }: { errors: Array<{ field: string; message: string }> }) {
  return (
    <ul>
      {errors.map(e => <li key={e.field}><strong>{e.field}</strong>: {e.message}</li>)}
    </ul>
  )
}

Security: What NOT to Include in JSON Errors

// WRONG — exposes internal details
res.status(500).json({
  error: 'Database query failed',
  detail: 'SELECT * FROM users WHERE id = $1',  // SQL exposed!
  stack: err.stack,                              // stack trace exposed!
  internalCode: 'DB_CONNECTION_POOL_EXHAUSTED',
})

// CORRECT — generic 500 with correlation ID for debugging
const correlationId = req.headers['x-request-id'] ?? crypto.randomUUID()
console.error({ correlationId, error: err.message, stack: err.stack })  // log internally

res.status(500)
  .type('application/problem+json')
  .json({
    type: 'https://api.example.com/errors/internal-error',
    title: 'Internal Server Error',
    status: 500,
    detail: 'An unexpected error occurred. Please try again.',
    instance: `/errors/${correlationId}`,  // correlation ID for support
  })

Definitions

RFC 9457

IETF standard defining Problem Details for HTTP APIs; specifies a machine-readable JSON format for error responses with type, title, status, detail, and instance fields.

Problem Details

The error response format from RFC 9457; Content-Type: application/problem+json; provides consistent, self-describing error information that clients can parse programmatically.

422 Unprocessable Entity

HTTP status code for requests where the body is syntactically valid but semantically invalid; used for field validation errors in REST APIs.

correlation ID

A unique identifier (UUID) generated per request and included in both the error response and server logs; enables tracing a specific request through distributed systems for debugging.

error extension member

An additional field in a Problem Details JSON object beyond the RFC 9457 base fields; used for application-specific details like validation field errors, rate limit info, or resource identifiers.

FAQ