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)
51 lines
2.0 KiB
Markdown
51 lines
2.0 KiB
Markdown
<!--
|
|
order: 13
|
|
-->
|
|
|
|
# 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:
|
|
|
|
+++ <https://github.com/cosmos/cosmos-sdk/blob/b2d48a9e815fe534a7faeec6ca2adb0874252b81/x/bank/keeper/keeper.go#L85-L122>
|
|
|
|
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.
|