API error handling with RFC 7807

Why structured errors

Unstructured error messages can leak stack traces and confuse clients. RFC 7807 introduced Problem Details for HTTP APIs; RFC 9457 now supersedes it. A problem document gives clients a consistent shape, but the service must still avoid putting sensitive values in its fields.

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 flags operations without a documented error response and checks whether documented error schemas contain the problem-details fields. It can also flag certain debug fields. It does not require both 4xx and 5xx on every operation or inspect live responses.

Define a problem type clients can rely on

The type member identifies the kind of problem, while title is a short summary. Use a stable URI for application-specific types and publish a short explanation of each one. A client can branch on the type without matching a translated sentence in detail. If the error has no more specific identity, about:blank is available; its meaning follows the HTTP status code. Avoid minting a new type for every individual occurrence of the same failure.

The status member can help consumers understand a stored problem body, but the actual HTTP response status must still be correct. The instance member can identify a particular occurrence; choose a value that does not expose a private path or customer identifier. Keep detail safe for a client to display, and put operational diagnostics in protected server logs. RFC 9457 allows extension members such as a request ID, so name and document them consistently.

Describe the response in OpenAPI

For each operation, document the errors a client can reasonably handle. A reusable response component can declare application/problem+json, a schema for the problem fields, and an example with harmless values. Reference that component from a 400, 401, 403, 404, or 429 response as appropriate. Do not claim a 429 on an operation that has no quota, and do not document a problem media type if the service still returns a different format.

An OpenAPI example should illustrate one concrete failure and the recovery decision. For a rate limit, show a matching Retry-After header. For invalid input, describe which fields are wrong without echoing raw secrets. This contract helps SDK generators and reviewers, but only integration tests prove the implementation uses it. Scan after editing to catch missing declarations, then trigger the failure in a test environment.

Handle validation errors without leaking data

A validation problem may need to name several fields. Use a documented extension containing safe field paths and messages; do not copy entire rejected request bodies into the response. Avoid returning password values, access tokens, raw database constraints, or file contents. If the API localises text, keep a stable type or code so clients do not need to parse the translated message. A request identifier can connect a customer's report to server logs without revealing internals.

Test malformed JSON, missing required fields, invalid enum values, and oversized bodies. Confirm that each path produces a predictable status and safe body. Exception handlers are often missed by ordinary happy-path tests, so deliberately exercise framework and proxy failures as well as application validation. The contract may document the intended result while a proxy still returns an HTML page; check the response at the boundary clients actually use.

Keep clients and operators in sync

Publish a short catalogue of problem types beside the API reference. For each type, state whether a client should fix the request, renew credentials, wait, or contact support. Version any semantic change to a type that would make an existing client take the wrong action. Monitor counts by type and operation; a rise in validation errors may signal a broken client release, while a rise in server errors may signal a dependency issue.

Problem Details improves consistency; it is not a substitute for good status codes, transport security, or authorization. Use the broader API error-handling guide for retry policy and error taxonomy, then use this article when implementing the response schema.

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.