❗ Error Reference

Learn about the standard JSON-RPC error codes and Alchemy's custom error codes.

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

Error Code



Bad Request -- Your request is invalid. Double-check your JSON-RPC body


Unauthorized -- You must authenticate your request with an API key. Check out how to create a key if you do not have one.


Forbidden -- You've hit your capacity limit, or your request was rejected by your app's whitelist settings.


Too Many Requests -- You've hit your rate limit. Check out the Rate Limits page for solutions.


Internal Server Error -- We're unable to process your request right now. Get in touch with us if you see this.

Example Response

// Example 401 Error
{"error": "Must be authenticated!"}

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


Possible Return message



Parse error

Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text.


Invalid Request

The JSON sent is not a valid Request object.


Method not found

The method does not exist / is not available.


Invalid params

Invalid method parameter(s).


Internal error

Internal JSON-RPC error.

-32000 to -32099

Server error

Reserved for implementation-defined server-errors.

Example Response

"message": "Invalid params: invalid length 63, expected a 0x-prefixed, padded, hex-encoded hash with length 64."

Custom Error Codes


Possible Return message




Should be used when some action is not authorized, e.g. sending from a locked account.


Action not allowed

Should be used when some action is not allowed, e.g. preventing an action, while another depending action is processing on, like sending again when a confirmation popup is shown to the user.


Execution error

Will contain a subset of custom errors in the data field. See below.

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:

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


Possible Return message



X doesn't exist

Should be used when something which should be there is not found. (Doesn’t apply to eth_getTransactionBy_ and eth_getBlock_. They return a success with value null)


Requires ether

Should be used for actions which require something else (gas or value)


Gas too low

Should be used when the value of gas given is too low


Gas limit exceeded

Should be used when a limit is exceeded (for the gas limit in a block)



Should be used when an action was rejected, e.g. because of its content (too long contract code, contains wrong characters, etc.)


Ether too low

Should be used when the value of Ether given is too low