Return API errors that clients can act on

An API error should help a client decide what to do next. A generic failure message can trigger blind retries, unnecessary support tickets, or a screen that blames the user. Start error design with client decisions rather than a list of server exceptions.

Give software a stable signal

RFC 9457 defines problem details for machine-readable error information in HTTP responses.[3] It provides members such as type, title, status, detail, and instance.[3] Use a stable problem type to identify a documented condition. Treat human-readable detail as an explanation, not a code that clients must parse.

Choose the actual HTTP response status to reflect the HTTP outcome. If you also include the problem status member, keep it consistent with that response. Do not hide a failed operation inside a successful response merely to simplify client networking code. Document partial results separately when the operation supports them.

Explain the next action without guessing

Recommend a small error catalog organized around recovery. A field validation problem should identify the affected input and correction rule. A permission problem should direct the user toward the appropriate access process, without revealing another tenant’s resources.

A temporary error does not by itself authorize repeating a business action. The original request might have completed before a response failed. Link retry instructions to the operation’s idempotency or status-check contract. For asynchronous work, distinguish an unsuccessful status lookup from the business job itself failing. This prevents a technical observation from becoming a false business conclusion.

Keep user-facing wording separate from stable error identifiers. This lets teams translate explanations without changing the conditions that client software recognizes and handles.

Review safety and usability together

RFC 9457 warns that problem details are not an implementation debugging tool and discusses the risk of exposing internals.[3] Keep stack traces, credentials, database statements, and private payloads in controlled diagnostic systems, not public error messages. Give support a safe correlation reference instead.

• Define a stable type and owner for each expected error condition.
• Give field errors a precise location and a usable correction rule.
• Specify whether to correct, authenticate, wait, check status, or contact support.
• Test unknown error types and ensure clients still fail safely.

Hypothetical example: a purchase approval

Hypothetical example: a purchasing tool rejects an approval because the request lacks a cost center. The response names the field and the accepted format. The client highlights that field and preserves the rest of the form.

If the approval service becomes unavailable after submission, the client shows an uncertain state and offers a status check. It does not tell the user to submit another approval immediately. Maintaining this catalog requires coordination as conditions change. Begin with the errors that currently create ambiguous user decisions, then test whether someone unfamiliar with the API can choose the correct next action.