Troubleshooting requests

Start with the response your application received. A node's JSON-RPC error, an unreachable gateway, and a payment failure need different remedies; retrying everything can hide the cause or repeat work unnecessarily.

For managed access, check the endpoint URL, access key, restrictions, and your account's balance. The local status and activity commands below apply to gateways you operate.

Check the gateway

First check the local gateway independently of the provider:

curl -s http://127.0.0.1:1337/direct/status

If that cannot be reached, check that the client is running and that you are using the port it reported. A working management endpoint does not by itself mean provider discovery has completed.

Inspect the failing call

Capture the response status, headers, and timing for the method that failed. Start with this basic read to check RPC access, then repeat with your actual method and parameters:

curl -sS -D /tmp/direct-rpc-headers.txt \
  -o /tmp/direct-rpc-response.json \
  -w 'HTTP %{http_code}; total %{time_total}s\n' \
  http://127.0.0.1:1337/service/ethereum \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}'

Read the response body before retrying. Provider headers identify the selected provider when one served the request; a gateway failure may have none. Use Errors to distinguish a node error from a connection or payment problem.

Inspect recent events

For a local gateway, inspect recent client events through the management API:

curl -s http://127.0.0.1:1337/direct \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"activity.list","params":{"limit":20}}'

Activity retains up to 1,000 recent events in memory and clears them on restart. It is useful for recent connection and service events, not a durable request log or billing ledger. Keep your own application logs when you need a history, and remove endpoint keys and sensitive data before sharing diagnostics.

Handle a limit

Symptom	Next step
HTTP 413	Reduce the serialized request size or split the batch
Log query rejected for range or result size	Use a smaller block range and retain the same filters
Timeout on a large query	Reduce the work per call before increasing application retries
Managed access throttled	Reduce request concurrency and follow the response's retry guidance

A failed batch is not evidence that none of its calls ran. Retry policy must account for the individual methods, especially transaction submission. See Routing requests and handling failures.

Retrying in your app

• Retry reads after transient 502 and 503 errors, with exponential backoff and some jitter: for example 200 ms, then 400 ms, then 800 ms, up to a few seconds, and give up after about five tries.
• Inspect the status and code. A 402 is a payment problem and a 503 with NO_PROVIDER_WITHIN_PRICE_LIMIT is your price ceiling; both need different action from a transient provider outage.
• Do not retry 404 or the node's errors about your request, such as invalid params or execution reverted. They will fail the same way.
• Retry -32603 once.
• For WebSockets closed with 1013, reconnect with the same backoff. Libraries that reconnect on close do this for you.

Managed gateways can enforce access limits in addition to Direct’s RPC limits. Reducing concurrency can help with throttling; it cannot fix an unsupported method or a query above a published limit.

Recover an interrupted transaction submission

A signed transaction can be sent any number of times: it has one hash, and the network includes it at most once. So when sending one fails with 502 or 503, or your app does not know whether it went through:

1. Keep the signed transaction and its hash.
2. Ask for it with eth_getTransactionByHash, or eth_getTransactionReceipt once it may be mined.
3. If no provider knows it, send the same signed bytes again with eth_sendRawTransaction.

Never sign a new transaction with a new nonce to retry: that can send it twice. already known indicates that the node knows the transaction. nonce too low requires checking the transaction hash and account state; it does not by itself confirm that this particular transaction succeeded.

Report an unresolved failure

Include the network, method, relevant parameters, time of failure, HTTP status, and error body. Where available, include provider headers and whether a retry succeeded. Remove endpoint keys, authorization headers, and sensitive request data before sharing logs.

Routing requests and handling failures explains automatic recovery. Errors lists response formats and codes.