# Troubleshooting Source: https://docs.graphops.xyz/rpc/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](#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 and includes RPC. 2. For header auth, confirm the header is exactly `Authorization: Bearer `. 3. For route-token auth, confirm the endpoint ends with `/` after the EVM chain ID or Bitcoin network name. 4. Confirm the key has not been revoked or rotated. 5. Confirm you send a query key, which starts with `gqk_`. RPC refuses a service account API key (`gsk_`) with the code [`api_key_class_not_allowed`](/platform/errors/api-keys#api_key_class_not_allowed). 6. Remove extra quotes, whitespace, or the literal string `Bearer` from secret-manager values. 7. Use [Authentication](./authentication) to compare header and route-token formats. ## `403 Forbidden` The key is valid, but GraphOps refuses the request. The response `code` names the reason. 1. `credits_exhausted`: the organization has no credits left. Add credits in **Billing** to bring the balance above zero. Access is restored automatically. To avoid a repeat, turn on [automatic top-ups](/platform/billing-and-credits#automatic-top-ups). 2. `api_key_route_not_allowed`: confirm the endpoint host and path match [Authentication](./authentication). 3. `api_key_target_not_allowed`: the key's RPC access is [limited](/platform/api-keys#limit-a-key) and does not include the network in the endpoint you call. Call an allowed network, or add this one to the key's limits. 4. `api_key_origin_not_allowed` or `api_key_origin_required`: the key limits RPC to [allowed origins](/platform/api-keys#use-a-key-in-a-browser). For a browser request, confirm one matches the page's origin exactly, including its scheme and port, such as `http://localhost:3000`. A server, script, or `curl` request sends no origin, so use a key whose RPC access has no allowed origins there instead. 5. `usage_access_paused`, `organization_disabled` or `api_key_disabled`: GraphOps support paused the organization or disabled the key. Adding credits does not restore access. Contact [support in the GraphOps Platform](https://platform.graphops.xyz/organizations/current/overview?support=open), or create a new key if only the key is disabled. ## `429 Too Many Requests` The organization exceeded its 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 limit increase through [support in the GraphOps Platform](https://platform.graphops.xyz/organizations/current/overview?support=open). ## 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](./concepts/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](./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](./guides/send-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//`. 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](./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](./guides/websocket-subscriptions#recover-after-a-disconnect) 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](https://platform.graphops.xyz/organizations/current/overview?support=open), 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 * [Authentication](./authentication): Compare header and route-token formats for your client. * [Retries and reorgs](./guides/retries-and-reorgs): Decide which errors to retry and how to recover from reorgs. * [Usage and limits](./usage-and-limits): Check the limits behind `429` and timeout errors.