Merge pull request #117 from paritytech/lexnv/chain-head-error-codes

chainHead: Define error codes returned by the server

Author: lexnv

src/api/chainHead_unstable_body.md

@@ -51,5 +51,6 @@ This function should be seen as a complement to `chainHead_unstable_follow`, all
 
 - If the networking part of the behaviour fails, then a `{"event": "operationInaccessible"}` notification is generated (as explained above).
 - If the `followSubscription` is invalid or stale, then `"result": "limitReached"` is returned (as explained above).
-- A JSON-RPC error is generated if the block hash passed as parameter doesn't correspond to any block that has been reported by `chainHead_unstable_follow`.
-- A JSON-RPC error is generated if the `followSubscription` is valid but the block hash passed as parameter has already been unpinned.
+- A JSON-RPC error with error code `-32801` is generated if the block hash passed as parameter doesn't correspond to any block that has been reported by `chainHead_unstable_follow`, or the block hash has been unpinned.
+- A JSON-RPC error with error code `-32602` is generated if one of the parameters doesn't correspond to the expected type (similarly to a missing parameter or an invalid parameter type).
+- A JSON-RPC error with error code `-32603` is generated if the JSON-RPC server cannot interpret the block (hardware issues, corrupted database, disk failure etc).

src/api/chainHead_unstable_call.md

@@ -57,11 +57,11 @@ This function should be seen as a complement to `chainHead_unstable_follow`, all
 
 - If the networking part of the behaviour fails, then an `{"event": "operationInaccessible"}` notification is generated (as explained above).
 - If the `followSubscription` is invalid or stale, then `"result": "limitReached"` is returned (as explained above).
-- A JSON-RPC error is generated if the `followSubscription` corresponds to a follow where `withRuntime` was `̀false`.
-- A JSON-RPC error is generated if the block hash passed as parameter doesn't correspond to any block that has been reported by `chainHead_unstable_follow`.
-- A JSON-RPC error is generated if the `followSubscription` is valid but the block hash passed as parameter has already been unpinned.
 - If the method to call doesn't exist in the Wasm runtime of the chain, then an `{"event": "operationError"}` notification is generated.
 - If the runtime call fails (e.g. because it triggers a panic in the runtime, running out of memory, etc., or if the runtime call takes too much time), then an `{"event": "operationError"}` notification is generated.
+- A JSON-RPC error with error code `-32801` is generated if the block hash passed as parameter doesn't correspond to any block that has been reported by `chainHead_unstable_follow`, or the block hash has been unpinned.
+- A JSON-RPC error with error code `-32802` is generated if the `followSubscription` corresponds to a follow where `withRuntime` was `false`.
+- A JSON-RPC error with error code `-32602` is generated if one of the parameters doesn't correspond to the expected type (similarly to a missing parameter or an invalid parameter type).
 
 ## About `callParameters`
 

src/api/chainHead_unstable_continue.md

@@ -13,4 +13,5 @@ Has no effect if the `operationId` is invalid or refers to an operation that has
 
 ## Possible errors
 
-- A JSON-RPC error is generated if the `followSubscription` and `operationId` are valid but haven't generated a `operationWaitingForContinue` event.
+- A JSON-RPC error with error code `-32803` is generated if the `followSubscription` and `operationId` are valid but haven't generated a `operationWaitingForContinue` event.
+- A JSON-RPC error with error code `-32602` is generated if one of the parameters doesn't correspond to the expected type (similarly to a missing parameter or an invalid parameter type).

src/api/chainHead_unstable_follow.md

@@ -400,3 +400,4 @@ The runtime is of type `invalid` if the JSON-RPC server considers the runtime as
 ## Possible errors
 
 - A JSON-RPC error with error code `-32800` can be generated if the JSON-RPC client has already opened 2 or more `chainHead_unstable_follow` subscriptions.
+- A JSON-RPC error with error code `-32602` is generated if one of the parameters doesn't correspond to the expected type (similarly to a missing parameter or an invalid parameter type).

src/api/chainHead_unstable_header.md

@@ -18,5 +18,6 @@ This function should be seen as a complement to `chainHead_unstable_follow`, all
 
 ## Possible errors
 
-- A JSON-RPC error is generated if the block hash passed as parameter doesn't correspond to any block that has been reported by `chainHead_unstable_follow`.
-- A JSON-RPC error is generated if the `followSubscription` is valid but the block hash passed as parameter has already been unpinned.
+- A JSON-RPC error with error code `-32801` is generated if the block hash passed as parameter doesn't correspond to any block that has been reported by `chainHead_unstable_follow`, or the block hash has been unpinned.
+- A JSON-RPC error with error code `-32602` is generated if one of the parameters doesn't correspond to the expected type (similarly to a missing parameter or an invalid parameter type).
+- A JSON-RPC error with error code `-32603` is generated if the JSON-RPC server cannot interpret the block (hardware issues, corrupted database, disk failure etc).

src/api/chainHead_unstable_storage.md

@@ -78,8 +78,8 @@ If a `{"event": "operationWaitingForContinue"}` notification is generated, the s
 
 ## Possible errors
 
-- A JSON-RPC error is generated if `type` isn't one of the allowed values (similarly to a missing parameter or an invalid parameter type).
 - If the networking part of the behaviour fails, then a `{"event": "operationInaccessible"}` notification is generated (as explained above).
 - If the `followSubscription` is invalid or stale, then `"result": "limitReached"` is returned (as explained above).
-- A JSON-RPC error is generated if the block hash passed as parameter doesn't correspond to any block that has been reported by `chainHead_unstable_follow`.
-- A JSON-RPC error is generated if the `followSubscription` is valid but the block hash passed as parameter has already been unpinned.
+
+- A JSON-RPC error with error code `-32801` is generated if the block hash passed as parameter doesn't correspond to any block that has been reported by `chainHead_unstable_follow`, or the block hash has been unpinned.
+- A JSON-RPC error with error code `-32602` is generated if one of the parameters doesn't correspond to the expected type (similarly to a missing parameter or an invalid parameter type).

src/api/chainHead_unstable_unpin.md

@@ -17,6 +17,6 @@ If this function returns an error, then no block has been unpinned. An JSON-RPC
 
 ## Possible errors
 
-- A JSON-RPC error is generated if the `followSubscription` is valid but at least one of the block hashes passed as parameter doesn't correspond to any block that has been reported by `chainHead_unstable_follow`.
-- A JSON-RPC error is generated if the `followSubscription` is valid but at least one of the the block hashes passed as parameter has already been unpinned.
+- A JSON-RPC error with error code `-32801` is generated if the `followSubscription` is valid but at least one of the block hashes passed as parameter doesn't correspond to any block that has been reported by `chainHead_unstable_follow`, or at least one of the block hashes has been unpinned.
+- A JSON-RPC error with error code `-32602` is generated if one of the parameters doesn't correspond to the expected type (similarly to a missing parameter or an invalid parameter type).
 - No error is generated if the `followSubscription` is invalid or stale. The call is simply ignored.