Error Format — problem+json

The status code says which kind of error; the body should say what specifically went wrong, in a shape that is identical across every endpoint. Inventing a new error shape per endpoint is a tax clients pay forever.

RFC 9457 Problem Details

There is a standard for exactly this: Problem Details for HTTP APIs (RFC 9457), served as application/problem+json. Its members:

type — a URI identifying the problem kind (a stable, documentable key).
title — a short, human-readable summary (stable per type).
status — the HTTP status code, repeated in the body.
detail — a human-readable explanation specific to this occurrence.
instance — a URI for this particular occurrence (often the request path).
plus any extension members you need (e.g. an errors array).

{
  "type": "https://api.example.com/problems/out-of-stock",
  "title": "Item is out of stock",
  "status": 409,
  "detail": "Only 2 units of SKU-123 remain; you requested 5.",
  "instance": "/orders/8821",
  "available": 2
}

Producing one in code

JavaScript

function problem(opts) {
  return {
    status: opts.status,
    headers: { 'Content-Type': 'application/problem+json' },
    body: {
      type: opts.type ?? 'about:blank',
      title: opts.title,
      status: opts.status,
      detail: opts.detail,
      instance: opts.instance,
      ...(opts.extra ?? {}),
    },
  };
}

const res = problem({
  status: 409,
  type: 'https://api.example.com/problems/out-of-stock',
  title: 'Item is out of stock',
  detail: 'Only 2 units remain; you requested 5.',
  instance: '/orders/8821',
  extra: { available: 2 },
});
console.log(res.headers['Content-Type']);
console.log(JSON.stringify(res.body, null, 2));