Troubleshooting

Find the error or symptom you see, then work through its checks in order. Each entry names the likely cause first. If the checks do not resolve the issue, contact support with the details listed in Need support.

401 Unauthorized

The request is missing a valid API key, the Authorization header is malformed, or the route-token URL does not include a valid key.

1. Confirm the key was created for the organization that owns RPC access.
2. For header auth, confirm the header is exactly Authorization: Bearer <GRAPHOPS_API_KEY>.
3. For route-token auth, confirm the endpoint ends with /<GRAPHOPS_API_KEY> after the EVM chain ID or Bitcoin network name.
4. Confirm the key has not been revoked or rotated.
5. Remove extra quotes, whitespace, or the literal string Bearer from secret-manager values.
6. Use Authentication to compare header and route-token formats.

403 Forbidden

The key is valid, but the organization is not entitled to the requested endpoint, network, or plan feature.

1. Confirm the organization has RPC enabled.
2. Confirm the endpoint network is included in the organization's plan.
3. Confirm archive access or WebSocket access is included if the failing request uses those features.

429 Too Many Requests

The organization exceeded a plan-specific rate or concurrency limit.

1. Reduce parallel requests.
2. Add exponential backoff with jitter.
3. Split large batch requests into smaller batches.
4. Move historical backfills to lower-concurrency workers.
5. Request a plan or limit change through support in the GraphOps Platform.

Timeouts or large eth_getLogs failures

The log query is too broad, the response is too large, or the archive read takes longer than the request timeout.

1. Reduce the block range.
2. Filter by contract address and topic whenever possible.
3. Persist progress and backfill in deterministic block chunks.
4. Avoid retrying the same broad range repeatedly.
5. Use WebSocket logs subscriptions for live logs and eth_getLogs for backfill.

Inconsistent results across requests

Separate latest reads can observe different blocks as the chain advances.

1. Read a block number or block hash first.
2. Pass that explicit block reference to subsequent state reads.
3. Use safe or finalized when the workflow can accept additional latency.
4. Avoid mixing latest reads with historical reads in the same consistency-sensitive workflow.
5. Use Consistency and finality for the repeatable-read pattern.

method not found

The request method name is misspelled, sent to the wrong endpoint, or is outside the standard Ethereum-compatible method set for the selected network.

1. Confirm the method name uses the exact eth_*, net_*, or web3_* casing.
2. Confirm the request is sent to an RPC endpoint, not the platform REST API.
3. Confirm the method is listed in Supported methods.
4. For WebSocket subscriptions, confirm the method is eth_subscribe and the endpoint is a WebSocket URL.

Transaction submission errors

Transaction errors usually come from EVM validation or mempool policy rather than from GraphOps itself.

1. Confirm the transaction was signed for the same chain ID as the endpoint.
2. Confirm the sender has enough funds for value plus gas.
3. Poll eth_getTransactionReceipt when the same transaction hash may already be known.
4. Use Send a raw transaction for nonce, replacement, and retry guidance.

WebSocket authentication fails

The WebSocket URL is missing the route token, the token is invalid, or the client is trying to use a header-based pattern that it does not support.

1. Prefer the route-token endpoint: wss://rpc.graphops.xyz/v1/evm/<chainId>/<apiKey>.
2. Confirm the API key is present after the chain ID and does not include the literal Bearer prefix.
3. If you use header authentication, confirm the WebSocket client can send custom headers during the handshake.
4. Redact route-token URLs from logs before sharing diagnostics.
5. Use Authentication for WebSocket auth patterns and security guidance.

WebSocket stream gaps

Connections can disconnect, subscriptions can expire, and live streams can miss events while a client is offline.

1. Store the last processed block or log position.
2. Reconnect with backoff.
3. Resubscribe after reconnect.
4. Backfill missed logs with eth_getLogs.
5. Deduplicate logs by (blockHash, transactionHash, logIndex).
6. Use WebSocket subscriptions for the full recovery sequence.

Empty eth_accounts

Hosted RPC does not custody user private keys. Account-management methods are present for client compatibility, but applications should sign with a wallet, signer service, or local key-management system.

1. Sign transactions in the wallet or application.
2. Submit signed transactions with eth_sendRawTransaction.
3. Do not rely on eth_sendTransaction, eth_sign, or eth_signTransaction for hosted key management.

Need support

When contacting GraphOps support, include:

• Organization name or ID.
• Network and endpoint.
• Transport: HTTPS or WebSocket.
• RPC method.
• Approximate timestamp.
• JSON-RPC error object or HTTP status.
• Block number, block range, or transaction hash if relevant.
• Whether the request used latest, safe, finalized, or an explicit block reference.

Next steps