Error reference

Check two layers: the HTTP transport and the JSON-RPC response body. The examples below illustrate common failures; exact upstream messages may vary by network and client.

Gateway layer

Case	HTTP	Shape
Invalid / revoked key	403	`auth error - specified api-key not found`
Key paused for the day (quota exceeded)	403	Method access is denied while the key is quota-paused. Check account usage and key status; this does not mean the secret is unknown. Recovery follows the UTC reset and gateway refresh.
IP or method access rule rejected	403	Check the key's access restrictions and the selected method; a 403 alone does not identify a quota problem.
Malformed JSON or invalid request	400	`-32700` or `-32600`; correct the request before retrying.
Request body or batch too large	413	`-32600`; split the batch or reduce the payload.
Rate or concurrency capacity exceeded	429	`-32005`; honor `Retry-After` and reduce request rate or parallelism.
Gateway could not complete the upstream exchange	502	`-32001`; timeouts and oversized responses are possible causes. Narrow large reads before retrying.
Upstream temporarily unavailable	200	`{"error":{"code":1,"message":"no available upstreams to process a request"}}` — retry with backoff.

jsonjson

{
  "id": 0,
  "jsonrpc": "2.0",
  "error": {
    "code": 403,
    "message": "auth error - specified api-key not found"
  }
}

JSON-RPC layer

Code	Meaning	Illustrative example / handling
`-32601`	Method not available on this platform	`the method eth_blobBaseFee does not exist/is not available` — see Unsupported methods for alternatives.
`-32602`	Invalid params	`invalid argument 0: json: cannot unmarshal hex string without 0x prefix…`
`-32000`	Implementation-defined execution or server error	Inspect `message` and `data`; insufficient funds and contract reverts require input or state changes, not blind retries.
`-32603`	Internal JSON-RPC error	Inspect the details before deciding whether the failure is transient.

HTTP 200 can still contain a JSON-RPC error. A non-2xx response can also carry JSON-RPC JSON, while an edge or transport failure may have a different body. Check both the status and the body before treating a call as successful.

Retry safely

Use bounded exponential backoff with jitter for transient failures and honor Retry-After. A timeout does not prove that a signed transaction was rejected: check its locally computed hash before rebroadcasting the same signed bytes. Do not create a new transaction merely because the submission response was lost.