API error handling with RFC 7807

Why structured errors

Unstructured error messages leak stack traces and confuse clients. RFC 7807 standardizes fields like type, title, status, and detail so consumers get consistent responses while limiting sensitive data exposure.

Sample payload

{
  "type": "https://apisast.com/errors/rate-limit",
  "title": "Too many requests",
  "status": 429,
  "detail": "Retry after 30 seconds",
  "instance": "/payments/1234",
  "trace_id": "b93f..."
}

Document this schema in OpenAPI and reuse it across services. Add retry hints and user-friendly guidance; avoid internal hostnames or stack traces.

Testing with static analysis

The OpenAPI security scanner checks that every operation defines 4xx and 5xx responses, uses the problem details schema, and omits sensitive fields. Link findings to monitoring so 5xx spikes trigger alerts.

Common pitfalls

• Returning HTML error pages to API clients.
• Embedding SQL or stack traces in detail.
• Using inconsistent field names across services.
• Forgetting to set cache headers on error responses.