Error Reference

HTTP Status Codes

In addition to the standard Ethereum JSON-RPC error codes, Alchemy will return the following status codes for HTTP requests:

HTTP Status Codes

Example Response

// Example 429 Error
{
    "jsonrpc": "2.0",
    "error": {
        "code": 429,
        "message": "Your app has exceeded its compute units per second capacity. If you have retries enabled, you can safely ignore this message. If not, check out https://docs.alchemyapi.com/guides/rate-limits"
    },
    "id": 1
}

Standard JSON-RPC Errors

For JSON-RPC specific errors, Alchemy returns a 200 with the JSON-RPC error in the JSON response.

JSON-RPC Error Codes

📘

NOTE:

-32000 is used for many server errors. Here are a few common examples:

"already known"

• This generally means the transaction already posted and is on the node in a pending state. Sometimes this error occurs when transactions fail at first but are retried when the node already knows of them

"Unspecified origin not on whitelist"

• This error means whoever is making the request is not on the whitelist for using your API key.

"filter not found"

• Filters expire after 5 minutes of inactivity so if it's not found the filter likely expired.

"Request timed out. Client should retry."

• Gateway timeouts (usually from nodes). Clients should retry the request.

"transaction underpriced"

• Transaction was sent with too low gas. Re-send the transaction with higher gas!

Example Response

{
    "jsonrpc":"2.0",
    "error":{
        "code":-32602,
        "message": "Invalid params: invalid length 63, expected a 0x-prefixed, padded, hex-encoded hash with length 64."
    },
    "id":1
}

Error Messages

• out of gas: not enough gas for the transaction or call, contact us at support

Kovan Error Codes

These errors should occur when using the Kovan network.

Custom Error Codes

Custom Error Fields

Custom error 3 can contain custom error(s) to further explain what went wrong.
They will be contained in the data field of the RPC error message as follows:

📘

NOTE:

Custom Error Fields are defined at the contract level. Therefore, the types within the error field might vary by contract. Read more about this here.

{
    code: 3,
    message: 'Execution error',
    data: [{
        code: 102,
        message: 'Innsufficient gas'
    },
    {
        code: 103,
        message: 'Gas limit exceeded'
    }]
}