From 104bb53f4d8f4f13af887d67839f7678c50f915d Mon Sep 17 00:00:00 2001 From: Roy Jones Date: Sat, 10 Jan 2026 20:23:17 +0100 Subject: [PATCH] Create ERROR_HANDLING_GUIDELINES.md added a clear set of error handling guidelines to help keep error behavior consistent, debuggable, and safe across MetaMask Core services. --- docs/ERROR_HANDLING_GUIDELINES.md | 40 +++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 docs/ERROR_HANDLING_GUIDELINES.md diff --git a/docs/ERROR_HANDLING_GUIDELINES.md b/docs/ERROR_HANDLING_GUIDELINES.md new file mode 100644 index 00000000000..1a14de1bd48 --- /dev/null +++ b/docs/ERROR_HANDLING_GUIDELINES.md @@ -0,0 +1,40 @@ +# Error Handling Guidelines + +This document defines recommended practices for handling errors +across MetaMask Core services and packages. + +## Error categories + +- Validation errors: invalid input, missing parameters +- Network errors: timeouts, unreachable services +- Dependency errors: upstream failures or unexpected responses +- Internal errors: unexpected states or logic failures + +## General principles + +- Fail fast on invalid input. +- Do not swallow errors silently. +- Preserve the original error context whenever possible. +- Avoid exposing sensitive implementation details. + +## Error messages + +- Messages should be clear and actionable. +- Prefer short descriptions over verbose logs. +- Do not include secrets, private keys, or tokens. +- Use consistent terminology across packages. + +## Logging and propagation + +- Log errors at the appropriate level (warn vs error). +- Attach contextual metadata (request ID, operation name). +- Propagate errors upward instead of converting everything to generic failures. + +## Testing + +- Add tests for expected failure cases. +- Assert both error type and message when applicable. +- Ensure errors remain stable across refactors. + +Consistent error handling improves debuggability, reliability, +and the developer experience across the MetaMask Core ecosystem.