Error Response Format — RFC 7807 Problem Details

In this tutorial, you will learn about Error Response Format. We cover key concepts, practical examples, and best practices to help you master this topic.

RFC 7807 Problem Details defines a standard error response format with fields for type, title, status, detail, and instance, enabling consistent machine-readable error handling.

Standard Format

{
  "type": "https://api.dodatech.com/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The request body contains invalid fields.",
  "instance": "/api/users",
  "errors": [
    {
      "field": "email",
      "detail": "Must be a valid email address"
    }
  ]
}

Implementation

function problemDetails(status, title, detail, instance, extra = {}) {
  return {
    type: `https://api.dodatech.com/errors/${title.toLowerCase().replace(/\s+/g, "-")}`,
    title,
    status,
    detail,
    instance,
    ...extra,
    requestId: generateRequestId(),
    timestamp: new Date().toISOString()
  };
}

app.get("/api/users/:id", (req, res) => {
  const user = findUser(req.params.id);
  if (!user) {
    return res.status(404).json(problemDetails(
      404,
      "Not Found",
      "The requested user does not exist",
      req.path
    ));
  }
  res.json(user);
});

Common Mistakes

1. Inconsistent format — Different endpoints return different error structures.
2. Missing type URL — The type field should link to documentation.
3. No instance field — Clients cannot identify which request failed.

Practice Questions

1. What are the standard RFC 7807 fields?
2. What is the purpose of the type field?
3. How do you extend the format for additional error details?

Challenge

Implement RFC 7807 Problem Details for all API errors. Create error type URLs with documentation, include request ID, and standardize across all endpoints.

What's Next

In the next lesson, you will learn validation error handling.