Skip to main content

Optimism Error Code Reference

Updated on
Nov 16, 2023

To facilitate a clear understanding of error codes, this document provides a list of possible error codes, along with additional information about how to resolve them.

HTTP Error Codes

Let's look at the common HTTP errors you can encounter, what they mean and what you can do to prevent them.

CodeMessageExplanation
400Bad RequestIncorrect HTTP Request type (e.g. using GET instead of POST) or Invalid Characters
401UnauthorizedThis can happen when one or multiple security requirements are not met such as incorrect Token Auth, IP not in the whitelist, invalid JWT, etc.
403ForbiddenEndpoint Disabled (One of the reasons for this could be a past due payment)
403Forbidden - custom trace not found in allowed custom tracesCustom trace code not whitelisted (Submit a ticket here to go through the approval process)
404Not FoundIncorrect URL or Incorrect method
413Content Too LargeBody of the request is too large
413Request Entity Too Large eth_getLogs and eth_newFilter are limited to a 10,000 blocks rangeWe enforce a limit of 10,000 block ranges when requesting logs and events. Learn more about why we have set the limit and what you can do to work around this here
429Too Many RequestsThe requests per second (RPS) of your requests are higher than your plan allows. Learn more about the 429 errors here
500Internal Server ErrorSubmit a ticket for the support team to take a look at the errors asap
503Service UnavailableSubmit a ticket for the support team to take a look at the errors asap

HTTP Error Code Example

The code snippet below is an example of Error Code 429.

HTTP Error Code Example

{
"jsonrpc": "2.0",
"error": {
"code": 429,
"message": "The requests per second (RPS) of your requests are higher than your plan allows."
},
"id": 1
}

EVM RPC Error Codes

Let's look at the common EVM errors you can encounter, what they mean and what you can do to prevent it.

CodeMessageExplanation
-32000header not found or could not find block XXXThe requested block doesn't exist on the node. Invalid block number or the node you're hitting is not in sync yet. Use a retry mechanism with an incremental timeout
-32000stack limit reached 1024 (1023)Usually a smart contract error/bug
-32000method handler crashedInternal error from the blockchain client, which can be a client bug. Submit a ticket so we can double check the nodes
-32000execution timeoutAdd the timeout param in your request to override the default client timeout. Read more about this here
-32000nonce too lowThe nonce value specified in your transaction is lower than the next valid nonce for the sender account.
-32000filter not foundFilter exceeded timeout; you'll have to recreate the filter once more. Read about it here
-32009trace requests limited to x/secWe have limited the debug and trace method to a specific RPS to prevent the nodes from overloading
-32010Transaction cost exceeds current gas limitGas limit is set too low
-32011network errorThis error occurs when there is a problem with the connection between the client and server, such as a timeout or a dropped connection
-32015VM execution errorSmart contract execution error
-32601method not foundTypically a typo in the method name; check for spelling errors
-32601failed to parse requestIncorrect request body; double check the method params
-32602invalid argument 0: json: cannot unmarshal hex string without 0x prefix into Go struct field CallArgs.to of type common.AddressIncorrect request; the 0x is missing from the address. the hex
-32602eth_getLogs and eth_newFilter are limited to a 10,000 blocks rangeRead an in-depth explanation here
-32603Internal JSON-RPC errorThis error is typically due to a bad or invalid payload
-32612custom traces are blockedSubmit a request here
-32613custom trace not found in allowed custom tracesSubmit a request here

The RPC errors defined above are a collection of common errors you can encounter while developing on chains like ETH, BSC, Polygon, etc. These chains run on multiple clients with their own error definitions. You can view those errors in the source code as well

EVM RPC Error Code Example

The code snippet below is an example of Error Code -32601.

EVM Error Code Example

{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32601,
"message": "the method eth_randomMethod does not exist/is not available"
}
}

If you're experiencing other error codes, please let us know by submitting a ticket. We're more than happy to assist 🚀

Share this doc