For AI agents: an LLM-friendly Markdown version of every page is available by appending .md to its URL or by sending an Accept: text/markdown request header. The full documentation index is at https://www.ankr.com/docs/llms.txt
Skip to main content

Troubleshooting

Every error string on this page was produced against production. Tool errors arrive as an error result with _meta.error_code, _meta.retryable, and a message that names the method and the chain.

The server connects but every tool call fails​

Error [INVALID_KEY]: HTTP 401 for eth_getBlockByNumber on eth

Cause. The key is wrong, revoked, or frozen. Connecting does not validate it: a session opens with any well-formed key, and the key is first checked when a tool actually calls the endpoint. A green server in /mcp says nothing about the key being good.

Fix. Confirm the key in the Web3 API platform, then reconnect the server so the new key is bound to a new session.

Connecting is refused outright​

{"code": -32001, "message": "Missing API key (x-ankr-api-key header or Bearer token)."}

Sent with HTTP 401. The header did not arrive. In Claude Code check the --header argument, in Cursor the headers object, in VS Code that the ${input:...} prompt was actually answered. There is no keyless mode.

A chain returns 404​

Error [UPSTREAM]: HTTP 404 for eth_getBlockByNumber on notachain

Cause. The chain slug does not exist. Slugs are the ones in rpc.ankr.com/<chain>, not display names.

Fix. Check the chains list, or call listChains, which also reports where indexer tools and tier-2 compression apply.

A method is refused​

Two different refusals, with different owners.

Refused by the server, on every chain.

rpcCall refused "eth_sendRawTransaction" locally, on every chain: it matches a write path
(broadcast, signing, transaction construction, node administration, or node/wallet state mutation)
and rpcCall is a read/data tool.

_meta.error_code is METHOD_NOT_ALLOWED. This is the design, not an outage: the data plane cannot broadcast or sign anywhere. Sign and send with your own wallet.

Refused by the endpoint, for your key on that chain.

Method disabled, reason: restricted by blockchain schema

That answer is authoritative and depends on your key, your tenant, and the chain's schema. Ask before you call:

Can I call trace_filter on Ethereum with this key?

describeMethods with probe: true puts the question to the endpoint instead of guessing. See the error reference for the underlying codes.

The response is raw hex, with no decoded args​

Check _meta.tier. Tier 2 is negotiated per call, not promised.

"_meta": { "token_count": 949, "tier": 2 }

A result at tier: 0 means the proxy declined to compress: the response was over its compression budget, or the method is one it never compresses (eth_call, eth_getCode, eth_getStorageAt).

Fix. Ask for less: a narrower block range, fewer transactions, one address instead of many. Treat a downgrade as a size signal, not an error. Some tools also set tier_degraded: true in the body, but not all do, so _meta.tier is the field to rely on.

A list came back short​

A wide range stops as soon as the display cap fills, and says so:

{
  "count": 5,
  "truncated": true,
  "more_available": true,
  "range_fully_scanned": false,
  "scanned_through_block": "25700031",
  "cursor": "eyJ0IjoibG9ncyIsImNoYWluIjoiZXRoIiwi..."
}

This is not an empty tail. range_fully_scanned: false means the later blocks were never fetched, so full_count is unknown and counting from this result is wrong. Continue with expandResult and the cursor, or narrow the range and ask again.

A new key does not work in the current session​

A session is bound to the key it was opened with, and every later request must present the same key. A key you just created, including one minted through the Management MCP, is not reachable from an open data-plane session.

Fix. Reconnect the server. The create and reveal replies also hand you a working rpc.ankr.com/<chain>/<token> URL you can call over plain HTTPS immediately.

Numbers look wrong by a factor of a million​

Decoded amounts are raw base units with no decimals applied. 10135766960 on a six-decimal token is 10,135.77, not ten billion. Read the token's decimals with resolveContract before reporting a human number. See the quickstart.

Related: pass block numbers above 2^53 as strings. A JSON number that large is not exact.

A tool argument is rejected​

Tool inputs are strict, so a misspelled argument is a validation error rather than a silently dropped field. Read the message: it names the argument it did not recognize.

Rate limits and cost​

Your key is passed straight through, so the rate limits and charging of your plan apply exactly as they do to your own calls. The server adds no quota of its own. One tool call is not always one request: a paged scan can make several, and _meta.upstream_calls reports how many.

Management MCP specifics​

  • Sign-in lands on the wrong account. There is no account switcher; the credential you sign in with decides the account. Assert the one you expect with expectAccount or mgmt_pin_account, and a call on the wrong account is refused instead of quietly succeeding.
  • A usage report for the last few minutes reads low. Rollups lag live traffic by longer than the smallest interval window.
  • An allowlist read does not list its entries, turning enforcement off is not effective today, and CIDR ranges are not accepted. Use the console to read a list back item by item.
  • A MetaMask-encrypted key cannot be revealed by a server. Decryption needs your own wallet key, so that one case belongs in the console.

Still stuck​

Collect the tool name, the chain, and the full error text including _meta.error_code, then request support. The error codes from the underlying endpoint are documented in the error reference.