Design API errors so HTTP status communicates the broad kind of failure, while a consistent, documented response body supplies stable identifiers and actionable context. For HTTP APIs, RFC 9457 Problem Details is a standards-based option; clients should branch on status and structured codes or problem types, never on the wording of a message.
Give the status code and response body distinct jobs
Choose an HTTP status code whose standardized meaning matches the broad failure. The body can then explain the API-specific condition that the status alone cannot identify. Do not flatten every failure into one generic status, or repurpose a status code to imply undocumented application semantics. RFC 9457 is designed to carry additional problem details without changing HTTP status meanings.
Use stable, documented identifiers for program behavior: a problem type URI, an API error code, or both. Treat human-readable text as guidance for people, not a machine interface. RFC 9457 advises consumers not to parse detail; extensions are the place for additional structured data.
Choose one documented error format
For an HTTP API that needs a common response envelope, consider RFC 9457 and the application/problem+json media type. Its standard members have different roles:
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →#1 Best Overall
type: a URI identifying the problem type. Keep it stable and document its meaning.title: a short summary of the problem type, not a substitute for a code or other structured field.status: the HTTP status associated with this occurrence.detail: an occurrence-specific human-readable explanation, when useful.instance: a URI reference identifying this occurrence; it can help support teams correlate a report with server-side records if designed safely.- Extension members: documented machine-readable data, such as an API-specific code or validation issues.
Specify which optional members your API returns and what its extensions mean. Do not require clients to inspect title or detail to choose a program path.
Keep vendor-specific formats distinct
RFC 9457 is not mandatory for every protocol or API. Google’s AIP-193 describes Google API errors using google.rpc.Status and canonical gRPC codes. Microsoft Graph documents its own error object. These are valid platform-specific approaches; do not combine fields from separate formats into an undocumented hybrid. Choose the format that fits the protocol and client ecosystem, then document and preserve it.
Rank #2
- Used Book in Good Condition
Write details that help callers recover
A useful message briefly states what failed and what the caller can do next. For example, “page_size must be between 1 and 100; send a value in that range” is more actionable than “Invalid request.” This is illustrative wording, not a claim about a particular API.
RFC 9457 says that detail, when present, should help the client correct the problem rather than provide debugging information. Google’s AIP-193 likewise calls for simple descriptive language without jargon and an actionable resolution. Keep variable values and other structured facts in fields rather than interpolating them into message prose; Google recommends structured metadata such as ErrorInfo in details for dynamic aspects.
Do not expose stack traces, SQL fragments, secrets, implementation class names, or internal hostnames. Keep private diagnostics in server-side logs with suitable access controls.
Make validation failures locatable and structured
For validation errors, identify the request field and the issue in a predictable structure. RFC 9457 demonstrates an errors extension whose entries can include a JSON Pointer and a concise detail. Microsoft Graph’s model uses concepts such as target and details. Select one model for your API and document it rather than making clients guess.
Decide whether a response reports one issue or all independent validation issues, and state that behavior in the contract. RFC 9457 recommends representing the most relevant or urgent problem when multiple unrelated problem types occur. A validation extension can still list multiple field-level issues within that problem type.
Illustrative RFC 9457 response
The following invented example uses RFC 9457 members plus an API-specific errors extension. The URI, status, occurrence identifier, code, and range are example data, not claims about a real service.
Recommended Free Tools
Best Value
HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
{
"type": "https://api.example.com/problems/validation-error",
"title": "Request validation failed",
"status": 422,
"detail": "Correct the listed fields and submit the request again.",
"instance": "/problem-occurrences/abc123",
"errors": [
{
"pointer": "#/page_size",
"code": "out_of_range",
"detail": "Must be between 1 and 100."
}
]
}Treat identifiers and response shape as API contract
Once clients depend on an error code, type URI, or response shape, changing it can disrupt them. Define identifiers early, document their meanings, and keep them stable. Google AIP-193 advises brownfield APIs that lack machine-readable identifiers to keep a given message stable; Microsoft warns that changing an error code visible to clients is breaking. Those are vendor-specific recommendations, but both reinforce the value of making structured identifiers the durable interface and prose the explanation.
Separate public guidance from private diagnosis
Return enough safe information to explain the interface-level problem and help the caller decide what to do. When support needs correlation, an appropriately designed instance identifier can connect the report to private server records. Log the detailed exception on the server; do not turn the public problem response into a debugging dump. RFC 9457 explicitly warns about security risks from exposing implementation details.
Choose a format against your actual constraints
Compare the options using criteria that affect implementation and deployed clients:
- Protocol fit: Is an HTTP media type and its fields appropriate, or do your services follow a platform’s RPC conventions?
- Client ecosystem: Do existing client libraries already consume a particular error model?
- Extension needs: Can the format carry stable domain codes and structured validation locations?
- Compatibility: What will clients experience if a code, message, or schema changes?
- Operational safety: Can support identifiers and public explanations be exposed without disclosing private diagnostics?
The goal is not to adopt every available convention. It is to select one consistent schema, document how callers should use it, and preserve that contract.
For the standards background, see RFC 9457, published in July 2023, which obsoletes RFC 7807.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
