> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.galleon8.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.galleon8.com/_mcp/server. # Ethereum Error Codes > Understand HTTP and Ethereum RPC errors for Ethereum API requests. Ethereum API requests can fail at two levels: * **HTTP errors** happen before or while the request reaches the endpoint. * **Ethereum RPC errors** come from the JSON-RPC request body or the backing Ethereum node. Successful JSON-RPC responses include a `result` value. Failed JSON-RPC responses include an `error` object with a `code`, `message`, and optional `data` field. ## HTTP Error Codes | Code | Message | Meaning | What to check | | ----- | ---------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | `400` | Bad Request | The request is malformed, uses an invalid body, or cannot be interpreted by the endpoint. | Confirm the request body is valid JSON and follows the JSON-RPC 2.0 shape. | | `401` | Unauthorized | Authentication failed or the request is missing valid credentials. | Check that the endpoint URL includes the correct project API key. | | `403` | Forbidden | The request is not allowed for the endpoint, project, origin, or enabled method set. | Confirm project access, allowed origins, billing state, and method availability. | | `404` | Not Found | The endpoint URL or requested route does not exist. | Check the endpoint URL, network path, and copied project endpoint. | | `405` | Method Not Allowed | The endpoint does not accept the HTTP method used by the request. | Use `POST` for JSON-RPC requests. | | `413` | Content Too Large | The request body is larger than the endpoint accepts. | Reduce payload size, block ranges, batch size, or log/filter scope. | | `415` | Unsupported Media Type | The request uses an unsupported `Content-Type`. | Send `Content-Type: application/json`. | | `429` | Too Many Requests | The request rate is higher than the available rate limit. | Slow down requests, add retries with backoff, or review your service plan limits. | | `500` | Internal Server Error | The endpoint or upstream node failed while processing the request. | Retry the request and check whether the issue is method-specific or temporary. | | `503` | Service Unavailable | The endpoint or upstream service is temporarily unavailable. | Retry with backoff and monitor service health before increasing traffic. | ## HTTP Error Code Example This response shows an HTTP-level rate limit error: ```json { "jsonrpc": "2.0", "error": { "code": 429, "message": "The request rate is higher than the available rate limit." }, "id": 1 } ``` ## Ethereum RPC Error Codes | Code | Message | Meaning | | -------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `-32700` | Parse error | Invalid JSON was received and could not be parsed. | | `-32600` | Invalid request | The JSON-RPC request is malformed or missing required fields. | | `-32601` | Method not found | The method name is misspelled or unavailable on the endpoint. | | `-32601` | Failed to parse request | The request body or method parameters could not be parsed. | | `-32602` | Invalid params | The method parameters are missing, malformed, or incompatible with the method schema. | | `-32602` | Missing `0x` prefix | A hex value, address, hash, or quantity is missing the required `0x` prefix. | | `-32602` | Block range limit exceeded | A logs or filter request covers more blocks than the endpoint accepts. | | `-32603` | Internal JSON-RPC error | The Ethereum node encountered an internal error while processing the payload. | | `-32612` | Custom traces are blocked | The requested custom trace behavior is not enabled for the endpoint. | | `-32613` | Custom trace not allowed | The requested custom trace is not allowed by the endpoint configuration. | | `-32000` | Header not found / Block not found | The requested block is not available, the block number is invalid, or the node is not synced to that block yet. | | `-32000` | Stack limit reached | Contract execution exceeded the EVM stack limit. | | `-32000` | Method handler crashed | The backing blockchain client failed while handling the method. | | `-32000` | Execution timeout | The request took longer than the client or endpoint timeout allows. | | `-32000` | Nonce too low | The transaction nonce is lower than the next valid nonce for the sender account. | | `-32000` | Filter not found | The filter expired, was removed, or is no longer available on the node serving the request. | | `-32001` | Resource not found | The requested resource does not exist or is unavailable. | | `-32002` | Resource unavailable | The requested resource is temporarily or permanently unavailable. | | `-32003` | Transaction rejected | The transaction failed validation or could not be accepted by the node. | | `-32004` | Method not supported | The requested method is not implemented or supported by the server. | | `-32005` | Limit exceeded | The request exceeds an allowed limit or quota. | | `-32006` | JSON-RPC version not supported | The `jsonrpc` version is missing or not supported. | | `-32009` | Trace requests limited | Trace or debug request volume exceeds endpoint limits. | | `-32010` | Transaction cost exceeds gas limit | The transaction gas limit is too low for the expected execution cost. | | `-32011` | Network error | The client, endpoint, or upstream node connection failed or timed out. | | `-32015` | VM execution error | Smart contract execution failed in the EVM. | | `3` | Execution reverted | The transaction or call reverted during execution because of contract logic, failed conditions, insufficient gas, or another EVM execution failure. | ## Ethereum RPC Error Code Example This response shows a method lookup error: ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": -32601, "message": "The method eth_randomMethod does not exist or is not available." } } ``` ## Error Monitoring Use W3api platform request monitoring and statistics to compare successful and failed requests by project, chain, method, and time range. When investigating errors, capture the endpoint, request timestamp, method name, request body, HTTP status, and JSON-RPC `error` object so you can identify whether the issue is caused by request shape, rate limits, endpoint access, or upstream Ethereum execution.