Error Codes

Chainnodes RPC Error Codes Explained


Scroll to see all CHAINNODES API error codes below

In the context of this document we define the following phrases:

  • OFTEN -> we are emitting this error often, most likely due to a client mistake of using our APIs wrongly
  • SOMETIMES -> can happen because of client or server errors, but still mostly due to mistakenly using our APIs the way they are not supposed to be used
  • RARELY -> happens nearly never because usage is obvious enough and only malicious actors would make this wrong
  • VERY RARELY -> server only errors which happen extremely rarely and shouldn't be expected in normal day to day activities

All of that can vary depending on your usage. If you obey rules and know the APIs, most of the errors won't ever happen. The percentages are averages on Chainnodes based on what we know.

Depending on your plan, you might have a 99.9% SLA guarantee. Error codes that are expected errors, as defined in the table below, do not count towards downtime.

As our API is based on the JSON-RPC spec (opens in a new tab), the error codes and messages received from our servers will always be formatted in the following format:

    "jsonrpc": "2.0",
    "error": {
        "message": "invalid api key",
        "code": 401
    "id": 1

Alternatively, we sometimes use the optional error.data object to provide additional details. Do not depend on this value in your code, but rather use it to debug manually if you receive unexpected errors. Also provide it if you request support in our public channels our via email. ☝️


If you receive a malformed response or a different format response, most likely it's a server error. You can message us about that on Telegram (opens in a new tab) or via Email Support. This should happen VERY RARELY.


Please do not contact us about "expected" errors unless you do not understand what's going on or think the error is wrong. Otherwise we can only repeat what's written in the table below.

Below is a list of error codes and messages Chainnodes API typically respond with and what they mean.

  • Error Code is the JSON-RPC Error Code returned
  • HTTP Status is the status code we return, which only applies to HTTP calls (not Websocket).
  • 'Client' means you can fix it by fixing your request. / 'Server' means it's an issue out of your direct control.
Error NameError CodeError MessageHTTP StatusExpected?Client/ServerDescriptionRarity
InvalidApiKey401invalid api key401YESCLIENTprovide your correct api keyOFTEN
UnknownMethod-32601the method $method does not exist/is not available200YESCLIENTuse a supported methodSOMETIMES
UnknownSubscription-32601$subscription subscription does not exist/is not available200YESCLIENTuse a supported subscription methodSOMETIMES
UnknownNetwork404unknown or unsupported network $network200YESCLIENTuse a supported network/chainSOMETIMES
InvalidJson-32700not a valid json200YESCLIENTyour json is brokenRARELY
InvalidJsonRPC-32600not a valid json rpc request200YESCLIENTyour json doesn't follow json-rpc specsRARELY
GenericServerError-32000server error200NOSERVERserver error that should recover automatically. try again.VERY RARELY
TimeoutError408request timed out200YES/NOSERVERyour query is too heavy and the timeout was reached. reduce query sizeRARELY
NonUniqueIdsInBatch-32600ids in batch not unique200YESCLIENTmake sure your batch has unique ids for all requestsSOMETIMES
NonArrayArgs-32602non-array args200YESCLIENTparameters of json-rpc need to be passed as an arraySOMETIMES
WsOnly406only supported on websocket/duplex connections200YESCLIENTsend only through websocket, not httpOFTEN
MissingParam-32602missing value for required argument $position200YESCLIENTsome parameter was not provided. please provideOFTEN
InvalidLogsFilter-32600invalid logs filter200YESCLIENTyour logs filter is broken. fix itOFTEN
InvalidArgument-32602invalid argument $position200YESCLIENTone of your parameters is the wrong typeOFTEN
EthGetLogsTooManyBlocks-32605query requests $num blocks but max is $num2200YESCLIENTquery less blocks at the same time in eth_getLogsSOMETIMES
BatchTooBig-32606Batch size too big.200YESCLIENTreduce your batch size (number of requests in the batch)RARELY
MonthlyRateLimit-32610monthly rate limit exceeded429YESCLIENTupgrade your plan to continue. don't send further requests before you do.SOMETIMES
PerSecondRateLimit429per second rate limit exceeded429YESCLIENTreduce your requests per second and back off for the given seconds or upgrade your plan, otherwise you will be banned even longerRARELY
TooManyWebsocketConnections429too many websocket connections200YESCLIENTclose some websocket connections or upgrade your plan, otherwise we will force close random websocket connections of yoursRARELY