Error Response Formats — RFC 7807 and JSON:API Standards

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

Standardized error response formats like RFC 7807 (Problem Details) and JSON:API Errors provide consistent, extensible structures that clients can parse programmatically.

What You'll Learn

• RFC 7807 Problem Details format
• JSON:API error specification
• Choosing and implementing a format

Why It Matters

Standard error formats enable generic error handling in client libraries. Developers write error middleware once instead of per-endpoint.

flowchart LR
    A["Error Response\nFormats"] --> B["RFC 7807\nProblem Details"]
    A --> C["JSON:API\nErrors"]
    A --> D["Custom\nConsistent Format"]
    B --> E["type, title,\nstatus, detail,\ninstance"]
    C --> F["code, source,\ntitle, detail,\nmeta"]
    style A fill:#dbeafe,stroke:#2563eb

Code Examples

// RFC 7807 Problem Details
{
  "type": "https://api.example.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "The request body contains invalid fields.",
  "instance": "/users",
  "errors": [
    {
      "field": "email",
      "message": "Must be a valid email address",
      "code": "INVALID_FORMAT"
    },
    {
      "field": "age",
      "message": "Must be a positive integer",
      "code": "INVALID_TYPE"
    }
  ]
}

// JSON:API Error format
{
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "source": {
        "pointer": "/data/attributes/email"
      },
      "title": "Invalid attribute",
      "detail": "Email must be a valid email address"
    }
  ]
}

# RFC 7807 response in Flask
from flask import jsonify

class ProblemDetail(Exception):
    def __init__(self, title, status, detail, instance=None, errors=None):
        self.type = f"https://api.example.com/errors/{title.lower().replace(' ', '-')}"
        self.title = title
        self.status = status
        self.detail = detail
        self.instance = instance
        self.errors = errors or []

@app.errorhandler(ProblemDetail)
def handle_problem(error):
    response = jsonify({
        "type": error.type,
        "title": error.title,
        "status": error.status,
        "detail": error.detail,
        "instance": error.instance,
        "errors": error.errors
    })
    response.status_code = error.status
    return response

Common Mistakes

1. Mixing Multiple Formats

Pick one format and use it consistently across all endpoints.

2. No Error Codes

Include machine-readable error codes alongside human-readable messages.

3. Missing Error Sources

For validation errors, tell the client which field caused the error.

4. Overly Generic Details

"Bad request" tells the client nothing. "Email is required" is actionable.

5. Not Documenting Error Formats

Document the error format in your API reference so clients know what to expect.

Practice Questions

1. What is RFC 7807's standard fields?
2. How does JSON:API structure error responses?
3. Why should error responses include machine-readable codes?
4. What is the purpose of the instance field in RFC 7807?
5. Can you use multiple error formats in one API?

Answers:

1. type, title, status, detail, instance.
2. As an array of error objects with code, source, title, detail.
3. So client code can handle specific errors programmatically.
4. It points to the specific URL that generated the error.
5. No. Choose one and use it consistently.

Challenge: Design an error response format for an API and implement it as middleware in Flask or Express. Support validation errors, auth errors, and server errors.

FAQ

What's Next

Explore Validation Errors for input validation patterns, then learn about Authentication Errors.