Stop Inventing Custom API Errors: A Guide to RFC 7807 Problem Details

RFC 7807 Problem Details is an official technical specification that defines a standard JSON format for describing errors returned by HTTP web APIs. Instead of having every software engineer create their own custom fields like message, err_code, or reason, this standard establishes predictable key names such as type, title, status, detail, and instance. This gives both computer programs and human developers a uniform way to understand exactly what went wrong during an API request.

The Everyday Analogy: Car Diagnostic Reports

Imagine taking your car to a mechanic when the check engine light comes on.

Option A: The mechanic hands you a piece of paper that simply says: "Car is broken. Cost: $300."

Option B: The mechanic hands you a standardized vehicle diagnostic report that lists the exact sensor code (e.g., P0300), a short title ("Random Cylinder Misfire"), the severity level, specific details ("Cylinder 3 failed 14 times in the past 10 miles"), and a reference link to the manufacturer's repair guide.

Option A leaves you guessing and forces you to ask ten follow-up questions. Option B gives you instant, structured clarity. RFC 7807 acts as that standardized diagnostic report for your web applications.

Why RFC 7807 Matters for Engineers

In modern software engineering, web applications are built by connecting multiple services together. Front-end user interfaces (like React apps) communicate with back-end servers running Express.js, which in turn communicate with databases or external payment systems.

When something fails—such as an invalid credit card or an out-of-stock product—the back-end server must notify the front-end application. Without a standard like RFC 7807, team A might structure errors as { "error": "Invalid payload" }, while team B uses { "statusCode": 400, "description": "Bad input" }.

This inconsistency causes real operational pain:

1. Fragile UI Code: Front-end developers must write endless conditional if/else checks to parse different error formats from different endpoints.
2. Wasted Debugging Hours: Software engineers spend extra time reading through server logs trying to figure out what a vague error message actually means.
3. Poor User Experience: Applications fail silently or show generic "An unknown error occurred" popups because the front-end couldn't parse the unexpected error structure.

By enforcing RFC 7807, teams agree on a single contract. Front-end apps can use one central error-handling mechanism to extract the exact field that failed and display a meaningful message to the user.

Code Example: Express.js Error Handler

Here is how you can implement an RFC 7807 compliant error handler in a Node.js and Express server. The custom HTTP content type for this standard is application/problem+json.

const express = require('express');
const app = express();

app.use(express.json());

// Route that triggers a validation error
app.post('/api/users', (req, res, next) => {
  const { email } = req.body;
  if (!email) {
    const error = new Error('Email field is required.');
    error.status = 400;
    error.type = 'https://api.example.com/errors/missing-field';
    error.title = 'Invalid Request Payload';
    error.instance = '/api/users';
    return next(error);
  }
  res.status(201).json({ message: 'User created' });
});

// Central RFC 7807 Error Handling Middleware
app.use((err, req, res, next) => {
  const status = err.status || 500;

  const problemDetails = {
    type: err.type || 'https://api.example.com/errors/internal-error',
    title: err.title || 'Internal Server Error',
    status: status,
    detail: err.message || 'An unexpected error occurred on the server.',
    instance: err.instance || req.originalUrl
  };

  // Set the standard RFC 7807 header
  res.setHeader('Content-Type', 'application/problem+json');
  res.status(status).json(problemDetails);
});

app.listen(3000, () => console.log('Server running on port 3000'));

Key Takeaway

RFC 7807 transforms unpredictable API errors into predictable, structured data that both machines and humans can process seamlessly. Adopting this standard eliminates entire classes of error-handling bugs, simplifies frontend integration, and establishes clear debugging contracts across your entire software ecosystem.

---

Enjoyed this breakdown? Support my open-source work on Buy Me a Coffee or explore react-hook-lab!

Originally published on my blog. You can read the alternative breakdown here.