Reliable digital operations depend on what a service does when the intended path is unavailable. This error handling checklist turns that question into reviewable decisions: what outcome was attempted, who can act, which response is safe, what evidence is needed, and when recovery stops. It applies to browser forms, APIs, workers, integrations, and operator tools. The checklist is deliberately practical. A team should be able to use it during design review, release readiness, an incident follow-up, or a contract change without translating vague principles into private guesses.
Use Problem Details for HTTP APIs for stable status and corrective detail, the OWASP Error Handling Cheat Sheet for disclosure and monitoring checks, Node.js error guidance for runtime propagation, and OpenTelemetry error recording for consistent protected context. These references anchor the checklist; the service owner still decides the local recovery route and evidence.
Make the failure handling decision explicit
Name the business outcome before naming an exception. A failed login, rejected payment, unavailable report, and duplicate import each require different next actions. Record the actors involved, the authoritative state, the safe public message, and the operator route. RFC 9457 offers a standard problem-details shape for HTTP APIs, including a type, title, detail, and instance, but the application must still decide what detail helps correction and what detail would disclose a secret or protected resource. Make the decision testable in examples.
Design the boundary before implementation
What belongs in the public response
Expose stable meaning, correction guidance, and a safe reference. Keep stacks, tokens, provider details, and unbounded payloads in protected evidence. The public contract should say whether work was refused, pending, completed, or uncertain, and should not force a caller to infer state from a generic status code or a browser timeout.
Separate validation, authentication, authorization, dependency availability, concurrency, and unexpected defects. Give each class a stable public code or problem type, a status meaning, a retry rule, and a protected evidence set. Do not let a global handler erase the distinction between a caller mistake and a server failure. For asynchronous work, define accepted, running, completed, failed, canceled, and unknown states. The API or UI should show enough meaning that a person does not repeat a mutation simply because a browser request timed out.
| Checklist class | Safe response | Evidence |
|---|---|---|
| Input | Correct the named field or rule | Code and bounded field context |
| Access | Deny without protected disclosure | Policy result and trace |
| Dependency | Wait, retry, or show pending | Attempts and dependency state |
| Defect | Fallback and support route | Protected diagnostic record |
Deliver in a controlled scope
Implement the checklist at one important journey and exercise it through the real client. Preserve valid input, return accessible correction guidance, propagate a correlation ID, redact sensitive values, and make mutation retries idempotent or duplicate-safe. Add timeout and retry bounds to every dependency that can wait. Test malformed input, denied roles, expired credentials, duplicate commands, late provider responses, worker crashes, and deploy interruptions. A feature gate can limit exposure, but it cannot replace a reconciliation procedure for work whose outcome is ambiguous.
Verify claims with authoritative guidance
Use RFC 9457 to check whether problem types and extensions are machine-readable and safe. Use OWASP's error handling guidance to challenge disclosure, status, and monitoring assumptions. Use Node.js error documentation when reviewing runtime propagation, and OpenTelemetry error conventions when deciding what context enters telemetry. These references do not decide the product's wording or owner. They provide a standard against which the local contract can be reviewed. Record the selected rule and the reason when the product needs a domain-specific variation.
| Verification question | Pass condition | Follow-up |
|---|---|---|
| Can the caller act? | Response names correction, wait, or escalation | Revise message or state |
| Can support trace it? | Safe ID reaches protected evidence | Fix propagation or access |
| Can the system stop? | Retry and timeout have bounds | Add terminal ownership |
| Can security review it? | No secret or topology disclosure | Redact or narrow detail |
Operate and improve the capability
Which signal should page an operator
Page on consequence and age, not on every exception. An old ambiguous write, a growing recovery queue, or a change in authorization denials may deserve action even when total error volume is low. Keep the alert tied to a decision such as contain, reconcile, contact, or investigate, and record why the threshold is appropriate for that journey.
Monitor errors by journey, class, release, dependency, and age. Include user-visible failures, pending work, retries, manual corrections, support contacts, and terminal items that never resolved. OpenTelemetry's guidance supports consistent recording, but detailed telemetry needs access control and retention. Review the oldest unresolved case alongside rates; averages can hide one consequential failure. Each signal needs an owner and action: narrow a rollout, repair a record, contact a customer, raise a dependency issue, or change a contract. Link recurring patterns to a test, guardrail, runbook, or product change.
Use a tiered recovery path
Not every failure deserves the same response time or escalation. A field correction can return immediately to the caller. A dependency outage may need a pending state and a bounded queue. An ambiguous payment or entitlement change may require reconciliation before another write. A security-sensitive denial may need containment and review even when the user sees only a neutral message. Define the tier from consequence, uncertainty, and time to harm, then attach an owner and service expectation to it.
The tier should also determine how much evidence is retained and who may view it. A low-risk validation error may need only a field code, while a suspected access event needs a protected actor class, resource, decision, and review trail. Keep the public response proportional and avoid exposing the signal that would help an attacker tune a probe. These choices belong in the checklist because they affect privacy, security, operations, and customer communication at once.
Set a maximum age for every recovery queue and make the oldest item visible. An unbounded queue is a hidden product promise that someone will eventually fix the work. When the age threshold is reached, the owner should choose among containment, customer communication, a broader incident response, or a deliberate acceptance of loss. Record that choice and the evidence used. The checklist is doing its job when it makes the expensive decision visible before an operator is forced to improvise.
Review queue age by consequence, not only by count. One overdue entitlement or payment case can matter more than hundreds of low-risk validation errors. Keep the escalation rule understandable to the person receiving the alert.
When the queue is clear, keep one synthetic case or rehearsal available so the path does not decay between incidents. A recovery control that has never been exercised is an assumption, not evidence.
| Recovery tier | Example | Required control |
|---|---|---|
| Immediate correction | Malformed date or missing field | Field-level response and preserved input |
| Bounded retry | Transient read or provider rate limit | Timeout, backoff, attempt cap, and terminal state |
| Reconciliation | Write may have completed after timeout | Durable request identity and authoritative lookup |
| Human repair | Partial batch or inconsistent record | Owned queue, before-state, approval, and audit |
| Security response | Suspicious access or credential event | Containment, protected evidence, and incident owner |
Make the tier visible in the design and in the support view. A queue that mixes immediate corrections with security investigations will either page too much or hide urgent work. A single retry policy across read and write operations will either waste capacity or duplicate effects. The response should tell the caller whether to correct, wait, poll, or contact support, while the operator view adds the evidence and authority needed for repair. Keep these views connected by a safe correlation reference and a durable operation identifier.
Rehearse the difficult case with a second operator
Create a small scenario pack: invalid input, denied access, late provider success, duplicate command, worker crash, log pipeline delay, and an alert that fires during a release. Have someone outside the implementation team locate the affected record, state what is known, choose the approved action, and write the customer update. Measure time to determine state and time to restore the intended outcome. The exercise is not a game of guessing the stack trace; it is a check that the organization can protect customers while evidence is incomplete.
Use the result to improve one artifact at a time. Add a problem-detail example, a redaction rule, a trace field, an alert query, a runbook step, an idempotency guard, or a targeted regression test. If the same exercise fails repeatedly, the recovery design is too dependent on a person or a fragile tool. Record the accepted limitation, its owner, and the date for review rather than hiding it behind a generic error message.
Keep the error vocabulary under change control
A public error type becomes part of the interface when a client branches on it or a support guide names it. Give changes a compatibility review, a migration note, and a deprecation date. Keep the internal exception chain available to authorized investigators, but do not expose it as the contract. When two errors have the same safe response and recovery, consider one type; when one type leads to different retry or repair actions, split it. Small, deliberate vocabulary changes are easier to test than a catalog that grows with every library upgrade.
Keep the checklist connected to the boundaries that carry the failure. The REST API contracts checklist helps define client-visible meaning; the GraphQL tradeoffs checklist helps when one request spans many fields; and the background jobs checklist covers retries, poison work, and terminal ownership. Use the same recovery vocabulary across these paths where the next action is genuinely the same.
Error handling checklist principles to keep
- Define failure from the interrupted outcome and the next safe action.
- Use stable public problem meaning and protected technical evidence.
- Classify retry, timeout, cancellation, partial work, and terminal ownership.
- Test errors through real user, API, worker, and operator paths.
- Use error trends to make one concrete product, code, test, or operations change.
Error handling checklist questions
The first review should cover a consequential journey, not every exception in the repository. Users should usually see a clear implication and action rather than technical detail. Retries are safe only when the operation and failure class support them. A support team needs a correlation reference and a status it can trust. A mature checklist is revisited when a dependency, contract, role, or deployment path changes, and after real incidents reveal a missing state or owner.
Conclusion: make error recovery reviewable
Error handling is part of reliable operations because every service eventually meets an invalid input, unavailable dependency, partial write, or unexpected defect. Use the checklist to make the response, evidence, recovery, and review explicit. When the next safe action is visible and the diagnostic record is protected, failure becomes a controlled state that teams can improve instead of a mystery passed to the next person.