RPC Errors

Understand common RPC errors and how to handle them.

What Could Go Wrong?

When API request fails, RPC server returns a structured error response with a limited number of well-defined error variants, so client code can exhaustively handle all the possible error cases. Our JSON-RPC errors follow verror convention for structuring the error response:

{
  "error": {
    "name": <ERROR_TYPE>,
    "cause": {
      "info": {..},
      "name": <ERROR_CAUSE>
    },
    "code": -32000,
    "data": String,
    "message": "Server error"
  },
  "id": "dontcare",
  "jsonrpc": "2.0"
}

Heads up

The fields code, data, and message in the structure above are considered legacy ones and might be deprecated in the future. Please, don't rely on them.

Here is the exhaustive list of the error variants that can be returned, organized by HTTP status code:

200 - Successful Response with Error Data

These errors occur when the request was processed successfully but the requested data could not be retrieved or an operation could not be completed due to various blockchain-related conditions.

ERROR_TYPE: HANDLER_ERROR

General Errors

These are general errors that can occur across different API endpoints.

ERROR_CAUSE	Reason	Solution
UNKNOWN_BLOCK	The requested block has not been produced yet or it has been garbage-collected (cleaned up to save space on the RPC node)	• Check that the requested block is legit • If the block had been produced more than 5 epochs ago, try to send your request to an archival node
INVALID_ACCOUNT	The requested account_id is invalid	• Provide a valid account_id
UNKNOWN_ACCOUNT	The requested account_id has not been found while viewing since the account has not been created or has been already deleted	• Check the account_id • Specify a different block or retry if you request the latest state
UNAVAILABLE_SHARD	The node was unable to found the requested data because it does not track the shard where data is present	• Send a request to a different node which might track the shard
NO_SYNCED_BLOCKS	The node is still syncing and the requested block is not in the database yet	• Wait until the node finish syncing • Send a request to a different node which is synced
NOT_SYNCED_YET	The node is still syncing and the requested block is not in the database yet	• Wait until the node finish syncing • Send a request to a different node which is

Access Keys

Errors specific to Access Keys API.

ERROR_CAUSE	Reason	Solution
UNKNOWN_ACCESS_KEY	The requested public_key has not been found while viewing since the public key has not been created or has been already deleted	• Check the public_key • Specify a different block or retry if you request the latest state

Accounts / Contracts

Errors specific to Accounts / Contracts API.

ERROR_CAUSE	Reason	Solution
NO_CONTRACT_CODE	The account does not have any contract deployed on it	• Use different account • Specify a different block or retry if you request the latest state
TOO_LARGE_CONTRACT_STATE	The requested contract state is too large to be returned from this node (the default limit is 50kb of state size)	• Send the request to a node with larger limits in order to view the requested state • Spin up your own node where you can increase the limits to view state
CONTRACT_EXECUTION_ERROR	The execution of the view function call failed (crashed, run out of the default 200 TGas limit, etc)	• Check error.cause.info for more details

Block / Chunk

Errors specific to Block / Chunk API.

ERROR_CAUSE	Reason	Solution
UNKNOWN_CHUNK	The requested chunk is not available or has been garbage-collected	• Check chunk ID validity • Try an archival node for older chunks
INVALID_SHARD_ID	The provided shard ID is invalid or doesn't exist	• Provide a valid shard ID within the network's shard range

Network

Errors specific to Network API.

ERROR_CAUSE	Reason	Solution
UNKNOWN_EPOCH	An epoch for the provided block can't be found in a database	• Check that the requested block is legit • If the block had been produced more than 5 epochs ago, try to send your request to an archival node •Check that the requested block is the last block of some epoch

Transactions

Errors specific to Transactions API.

ERROR_CAUSE	Reason	Solution
INVALID_TRANSACTION	An error happened during transaction execution	• See error.cause.info for details, likely a field in the transaction was invalid •If error.cause.info is ShardCongested, resubmit the identical transaction after a delay. (Consider adding a priority fee once NEP-541 is released.) • If error.cause.info is ShardStuck, you may also resubmit the identical transaction after a delay
UNKNOWN_RECEIPT	The receipt with the given receipt_id was never observed on the node	• Check the provided receipt_id is correct • Send a request on a different node

400 - Bad Request

These errors indicate that the request was malformed or contains invalid parameters that prevent the server from processing it.

ERROR_TYPE: REQUEST_VALIDATION_ERROR

ERROR_CAUSE	Reason	Solution
PARSE_ERROR	Passed arguments can't be parsed by JSON RPC server (missing arguments, wrong format, etc.)	• Check the arguments passed and pass the correct ones • Check error.cause.info for more details

408 - Request Timeout

These errors occur when a request takes too long to process and times out before completion.

ERROR_TYPE: REQUEST_VALIDATION_ERROR

Transaction Timeouts

Errors specific to Transactions API that occur due to timeout conditions.

ERROR_CAUSE	Reason	Solution
TIMEOUT_ERROR	Transaction was routed, but has not been recorded on chain in 10 seconds.	• Resubmit the request with the identical transaction (in NEAR Protocol unique transactions apply exactly once, so if the previously sent transaction gets applied, this request will just return the known result, otherwise, it will route the transaction to the chain once again) • Check that your transaction is valid • Check that the signer account id has enough tokens to cover the transaction fees (keep in mind that some tokens on each account are locked to cover the storage cost)

500 - Internal Server Error

These errors indicate that something went wrong on the server side, typically due to internal issues or server overload.

ERROR_TYPE: INTERNAL_ERROR

ERROR_CAUSE	Reason	Solution
INTERNAL_ERROR	Something went wrong with the node itself or overloaded	• Try again later • Send a request to a different node • Check error.cause.info for more details