The JSON-RPC specification mandates the return of an error object with specific codes for failed requests (see JSON-RPC Error Specification). Our current node API implementation only provides data or a generic error message, omitting these specific error codes. As we continue to develop a comprehensive canonical API that will address this in the future, we can start improving our existing API by introducing error codes for common error scenarios. Initially, we don’t need a full set of refined error codes; we can implement a basic set and expand and refine these codes gradually based on user feedback and system requirements.
To streamline this process, we should establish an infrastructure to wrap all errors in a generic "Internal error" code, which can later be detailed into more specific codes as we refine our error handling strategy. This initial step will help standardize our error responses and make them more predictable for API users.
Implementation ideas
Node may utilise go-jsonrpc existing functionality for error codes, by providing global map of error codes to server and client via WithErrors option: https://github.com/filecoin-project/go-jsonrpc/blob/e75dcdc8133848b9b60335d5779e3af1ac3cb447/options.go#L88
It will allow go clients to use golang native errors.Is call to identify which error is returned. Other language clients would need to parse error code from response json object and map it to proper error value.
Some basic error codes that were requested include:
[ ] "rpc error: code = Unknown desc = timed out waiting for tx to be included in a block" error is returned frequently possibly due to 1) mempool congestion 2) big blobs 3) too small timeout_broadcast_tx_commit
[ ] ": tx already in mempool" always happens immediately after the above error and requires waiting out until the tx drops from the mempool
[ ] ": incorrect account sequence" occasionally happens in place of the above error but also requires waiting out until the tx drops from the mempool
[ ] rpc error: code = Unknown desc = error on broadcastTxCommit: tx size is too big: 1962442, max: 1962441 happens when submitting big blobs due to padding shares even though the supposed limit is 1974272 so this breaks the contract with node.
[ ] rpc error: code = Unknown desc = error on broadcastTxCommit: tx too large occasionally big blobs return this in place of the above. I see that there's also Tx too large. Max size is %d, but got %d in the code.
Adding error codes will enhance error traceability and debugging, making our API more robust and user-friendly in the interim period before the canonical API rollout.
liamsi
commented
1 week ago
Implementation ideas
The JSON-RPC specification mandates the return of an error object with specific codes for failed requests (see JSON-RPC Error Specification). Our current node API implementation only provides data or a generic error message, omitting these specific error codes. As we continue to develop a comprehensive canonical API that will address this in the future, we can start improving our existing API by introducing error codes for common error scenarios. Initially, we don’t need a full set of refined error codes; we can implement a basic set and expand and refine these codes gradually based on user feedback and system requirements.
To streamline this process, we should establish an infrastructure to wrap all errors in a generic "Internal error" code, which can later be detailed into more specific codes as we refine our error handling strategy. This initial step will help standardize our error responses and make them more predictable for API users.
Implementation ideas
Node may utilise go-jsonrpc existing functionality for error codes, by providing global map of error codes to server and client via WithErrors option: https://github.com/filecoin-project/go-jsonrpc/blob/e75dcdc8133848b9b60335d5779e3af1ac3cb447/options.go#L88 It will allow go clients to use golang native
errors.Iscall to identify which error is returned. Other language clients would need to parse error code from response json object and map it to proper error value.Some basic error codes that were requested include:
[ ] blob.GetAll: Error codes needed for scenarios such as [list specific errors here].](https://github.com/celestiaorg/celestia-node/issues/3292)
Cross posted from https://github.com/celestiaorg/celestia-node/issues/3335#issuecomment-2079748320 :
Adding error codes will enhance error traceability and debugging, making our API more robust and user-friendly in the interim period before the canonical API rollout.