API Error Shape Builder

// RFC 7807 Problem Details (application/problem+json)

// TypeScript interface:
interface ProblemDetail {
  type: string;        // URI identifying the problem type
  title: string;       // Short human-readable summary
  status: number;      // HTTP status code
  detail?: string;     // Human-readable explanation for this occurrence
  instance?: string;   // URI of the specific problem occurrence
  [key: string]: unknown; // Extension members
}

// Examples:
{
  "type": "https://api.example.com/errors/validation-error",
  "title": "Validation Failed",
  "status": 422,
  "detail": "Human-readable explanation of the problem.",
  "instance": "/api/v1/resource/123"
}

{
  "type": "https://api.example.com/errors/not-found",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "Human-readable explanation of the problem.",
  "instance": "/api/v1/resource/123"
}

{
  "type": "https://api.example.com/errors/unauthorized",
  "title": "Authentication Required",
  "status": 401,
  "detail": "Human-readable explanation of the problem.",
  "instance": "/api/v1/resource/123"
}

{
  "type": "https://api.example.com/errors/rate-limited",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Human-readable explanation of the problem.",
  "instance": "/api/v1/resource/123"
}

// Next.js API route:
return NextResponse.json(problem, {
  status: problem.status,
  headers: { "Content-Type": "application/problem+json" },
});