Error handling is the design of what happens when the intended outcome cannot proceed normally. It is not the same as printing an exception or returning a generic “something went wrong.” A person needs a safe next step, a client needs stable machine meaning, a support agent needs a way to identify the case, and an engineer needs protected context that explains the cause. Treat those as coordinated outputs. The result should help the right audience act without exposing secrets, encouraging unsafe retries, or turning an uncertain state into a false success.
Start with the interrupted outcome
Describe the operation before describing the error. “A customer tried to submit a return,” “a worker attempted to issue an invoice,” or “a user requested a report” gives the team a reference for deciding whether the result is refused, incomplete, unknown, or successful. A timeout after an external write is not the same as a validation failure before the write. If the system cannot tell, expose uncertainty and provide a reconciliation path rather than guessing.
| Audience | Needs to know | Do not expose |
|---|---|---|
| Person | What can be corrected or tried next. | Stack trace, secret, or internal topology. |
| Client | Stable status, code, retry meaning, and field detail. | Prose that must be parsed as a protocol. |
| Support | Correlation or case identifier and safe context. | Unfiltered personal or security data. |
| Operator | Dependency, release, state, and recovery evidence. | More data than the responder is authorized to see. |
| Security team | Pattern, rate, and protected diagnostic detail. | A public response that helps reconnaissance. |
Classify failures by the next safe action
Use categories that lead to behavior: correct input, authenticate, request access, resolve a conflict, retry later, wait for asynchronous work, contact support, or investigate a system fault. A domain rule such as “limit exceeded” may be expected and correct, even though it prevents the requested operation. An unexpected exception needs different telemetry and usually a generic public response. The category should be stable enough for clients and support to act without matching on a sentence.
Keep “unknown” as a first-class state. If a payment provider times out after accepting a request, the service may not know whether the payment completed. Returning “failed—try again” can create a duplicate charge. Return a pending or reviewable outcome, carry a correlation identifier, and reconcile with the authority. The HTTP semantics specification helps distinguish method and status meaning; the product still decides how an uncertain business operation is represented.
Shape a public error contract that machines can trust
For an HTTP API, use the status code for broad protocol meaning and a stable problem type or application code for the specific condition. RFC 9457 defines a problem-details model with type, status, title, detail, and instance fields plus extension members. Its Problem Details guidance also cautions that detail should help the client correct the problem, not serve as a debugging dump. Keep field-level validation errors structured so a client can point to the correct input without parsing prose.
| Failure class | Public representation | Machine behavior |
|---|---|---|
| Invalid input | Field or rule detail that can be corrected. | Do not retry unchanged input. |
| Unauthenticated | Prompt for a valid identity or session. | Refresh or sign in according to policy. |
| Forbidden | Safe access explanation without resource leakage. | Do not probe or repeat without a new authority. |
| Conflict | Current-state explanation and resolution route. | Reload, reconcile, or ask for a new decision. |
| Transient dependency | Temporary message and retry guidance if safe. | Back off and bound attempts. |
| Unknown result | Pending or reviewable status with identifier. | Do not create a duplicate effect. |
Do not make consumers parse title or detail to decide whether to retry. Use a stable code or type, document whether it is retryable, and keep the contract versioned with the client. If a public response contains an instance identifier, make it opaque and safe to share with support. The status member in a problem document is advisory to consumers; the actual HTTP status remains the protocol signal generic clients use.
Bound retries with idempotency and state awareness
A retry is an additional attempt at an operation, not a universal recovery plan. Retry only failures that are likely temporary and operations that are safe to repeat. Use idempotency keys, deduplication records, or a state transition that recognizes the same business intent. Set a maximum attempt count, backoff, timeout, and terminal route. For a background job, preserve attempt history and move poison work to an inspectable queue; the background jobs guide provides a useful companion.
Separate connection failure from business rejection. Repeating invalid input increases load and hides a client defect. Repeating a conflict without refreshing state can overwrite a newer decision. Repeating an external call after an ambiguous timeout may duplicate a side effect. The operation’s state model should tell the caller whether it is refused, in progress, complete, or unknown. That state is more valuable than a generic retry-after suggestion.
Protect diagnostics while keeping them useful
Public error text should not reveal stack traces, framework versions, SQL fragments, internal hostnames, account existence, tokens, or private records. OWASP’s Error Handling Cheat Sheet treats error handling as part of application security because unhandled detail can assist reconnaissance. Capture the protected cause, release, dependency, route, actor class, correlation, and state needed by an authorized responder, then scrub secrets and personal data at the logging boundary.
Use a correlation or instance identifier that appears in the public response and protected evidence. Do not make the identifier a bearer credential or expose the whole diagnostic record through a guessable URL. Support should be able to search the identifier under its access policy; engineering should be able to trace the request, job, or event; security should be able to review patterns without requiring a customer’s private payload.
Make error signals lead to an action
Structure logs and traces around the operating question. Track error code, route, operation, dependency, release, tenant class where appropriate, retry result, duration, and recovery state. The OpenTelemetry logging specification and Logs Data Model provide a common way to represent records and context across sources. Use that model to make signals joinable, not to collect every possible field.
Alert on conditions that change a decision: a rise in validation errors after a client release, an increase in unknown payment results, a dependency timeout that exhausts retries, or a growing age of unresolved cases. A count of exceptions without an owner or threshold is not an operational control. Annotate releases and configuration changes so a responder can distinguish a code regression from an upstream outage or a traffic shift.
Exercise the hard path before release
Test malformed input, expired authentication, denied access, conflict, duplicate action, timeout before a write, timeout after a write, dependency outage, partial completion, process restart, and malformed downstream error. For each case record the expected business state, public response, protected telemetry, retry behavior, and human route. The authentication flows guide is relevant when login or recovery errors carry assurance consequences, while the test strategy guide helps turn those cases into repeatable evidence.
Use contract tests for client-visible codes and property or integration tests for state transitions. Run a rehearsal with someone who did not build the feature: can they find the identifier, explain what happened, and choose the safe next action? A test that proves an exception was thrown is weaker than a test that proves the system leaves the record in a recoverable state. Keep the expected behavior near the change so future maintainers can repeat the exercise.
Roll out error changes without breaking clients
Add stable codes and correlation identifiers alongside existing messages before removing brittle client parsing. Treat a change in status, problem type, field detail, or retry meaning as a contract change. Release the new representation to a bounded client cohort, monitor unknown-code and retry rates, and keep a fallback for clients that have not migrated. Do not let a generic gateway error erase a useful downstream category; translate it deliberately at each boundary.
Turn recurring failures into safer design
Review error distributions after each meaningful release. Group by action, not only exception class. A rising validation category may point to a client contract change; an unknown-result category may point to weak idempotency or a provider timeout; a growing permission denial may be a policy or onboarding issue. Ask what changed in the boundary, evidence, or recovery path, then improve the control that would have made the condition easier to handle.
Keep a short decision record for accepted limitations: why a fallback is safe, how long a manual route may remain, who owns the reconciliation, and which signal reopens the design. Error handling becomes part of product quality when support, product, engineering, and security can describe the same failure without translating private jargon.
Key takeaways
- Start from the interrupted business outcome and classify the next safe action.
- Return stable machine meaning and useful corrective detail without exposing diagnostics.
- Treat unknown results, idempotency, retry budgets, and recovery queues as explicit state.
- Correlate public identifiers with protected logs and traces under an access policy.
- Test hard paths and use error distributions to improve the next release.
Frequently asked questions
What should an error response tell a user or client?
It should explain the next safe action: correct input, authenticate, request access, retry later, wait, contact support, or investigate. Use stable codes for machines and keep implementation detail in protected evidence.
When is retrying an error safe?
Retry only when the failure is likely temporary, the operation is idempotent or deduplicated, and attempts are bounded. Do not retry validation failures, conflicts, or ambiguous writes without a state or reconciliation check.
Should APIs return stack traces for debugging?
No. Return a safe problem representation and an opaque correlation or instance identifier. Put stack traces and detailed context in protected logs and traces that authorized responders can search.
Conclusion: make the next safe step obvious
Error handling is dependable when each audience receives the meaning and evidence it needs. Classify the failure, preserve state, bound retries, protect diagnostics, and rehearse recovery. A good error response does not pretend that the system is perfect; it helps people and software act safely when it is not.