58597139fa
## Description Closes: #9404 --- ### Author Checklist *All items are required. Please add a note to the item if the item is not applicable and please add links to any relevant follow up issues.* I have... - [x] included the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title - [ ] added `!` to the type prefix if API or client breaking change - [x] targeted the correct branch (see [PR Targeting](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#pr-targeting)) - [x] provided a link to the relevant issue or specification - [ ] followed the guidelines for [building modules](https://github.com/cosmos/cosmos-sdk/blob/master/docs/building-modules) - [ ] included the necessary unit and integration [tests](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#testing) - [ ] added a changelog entry to `CHANGELOG.md` - [ ] included comments for [documenting Go code](https://blog.golang.org/godoc) - [ ] updated the relevant documentation or specification - [x] reviewed "Files changed" and left comments if necessary - [x] confirmed all CI checks have passed ### Reviewers Checklist *All items are required. Please add a note if the item is not applicable and please add your handle next to the items reviewed if you only reviewed selected items.* I have... - [ ] confirmed the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title - [ ] confirmed `!` in the type prefix if API or client breaking change - [ ] confirmed all author checklist items have been addressed - [ ] reviewed state machine logic - [ ] reviewed API design and naming - [ ] reviewed documentation is accurate - [ ] reviewed tests and test coverage - [ ] manually tested (if applicable)
2.0 KiB
Errors
This document outlines the recommended usage and APIs for error handling in Cosmos SDK modules. {synopsis}
Modules are encouraged to define and register their own errors to provide better context on failed message or handler execution. Typically, these errors should be common or general errors which can be further wrapped to provide additional specific execution context.
Registration
Modules should define and register their custom errors in x/{module}/errors.go. Registration
of errors is handled via the types/errors package.
Example:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0/x/distribution/types/errors.go#L1-L21
Each custom module error must provide the codespace, which is typically the module name (e.g. "distribution") and is unique per module, and a uint32 code. Together, the codespace and code provide a globally unique Cosmos SDK error. Typically, the code is monotonically increasing but does not necessarily have to be. The only restrictions on error codes are the following:
- Must be greater than one, as a code value of one is reserved for internal errors.
- Must be unique within the module.
Note, the Cosmos SDK provides a core set of common errors. These errors are defined in types/errors/errors.go.
Wrapping
The custom module errors can be returned as their concrete type as they already fulfill the error
interface. However, module errors can be wrapped to provide further context and meaning to failed
execution.
Example:
Regardless if an error is wrapped or not, the Cosmos SDK's errors package provides an API to determine if
an error is of a particular kind via Is.
ABCI
If a module error is registered, the Cosmos SDK errors package allows ABCI information to be extracted
through the ABCIInfo API. The package also provides ResponseCheckTx and ResponseDeliverTx as
auxiliary APIs to automatically get CheckTx and DeliverTx responses from an error.