Errors

Look up JSON-RPC errors, gateway HTTP responses, and WebSocket close codes here. For a diagnostic procedure and application retry guidance, see Troubleshooting requests.

Two kinds of error

Distinguish JSON-RPC errors from failures to obtain a response:

	Where it comes from	What it looks like
JSON-RPC errors	The node rejected the call, or the client rejected malformed input	A JSON-RPC response with an error object, as the node sent it, over HTTP 200
Direct's own errors	The client could not get the request to a node and back	An HTTP status that is not 200, with a JSON error code and message

A gateway failure does not establish whether an upstream executed the request. Transaction recovery must account for an interrupted response.

JSON-RPC errors

Node errors pass through in their JSON-RPC format. Invalid input can also be rejected locally with the corresponding JSON-RPC code:

Code	Meaning	Retry?
-32700	The request is not valid JSON	No: fix the request
-32600	The request is not valid JSON-RPC	No: fix the request
-32601	The method is unsupported or does not exist	No
-32602	Invalid params	No: fix the params
-32603	Internal error in the node	Once, after a short wait
-32000 and nearby	Server errors with a message, such as execution reverted, nonce too low, insufficient funds, missing trie node	Depends on the message: see below

Some -32000 messages are about your request, not about the node:

• execution reverted is the contract refusing the call. Retrying gives the same answer.
• nonce too low, already known, or replacement transaction underpriced require checking transaction state before resubmission. See Recover an interrupted transaction submission.
• missing trie node or header not found at an old block means that node does not hold the history you asked for. Check that the request is routed to a provider with the required state coverage; see Troubleshooting requests.

A request that is not valid JSON-RPC is refused by the client before it reaches a provider, with the same codes.

Direct's own errors

When the gateway cannot serve a request, it returns an HTTP error status and a JSON body with a machine-readable error.code and a descriptive error.message:

Status	When	What to do
403	A local service request fails host or origin checks	Use the loopback address; browser applications should use a managed gateway or your own HTTPS endpoint
413	The local request body is too large	Split the request or batch
404	The path names no offering, such as a typo in /service/<chain>	Check the chain name in the URL
502	A provider failed after it took the request, and no other could serve it in its place	Retry reads. For a transaction, see Recover an interrupted transaction submission
503	No compatible provider could be reached or used	Retry with backoff; inspect error.code before deciding whether to retry
402	Nothing is set aside to pay a provider, the funds set aside for one ran out, or the provider refused the payment, for example because the device is frozen	Add funds, or check the device in your account
429	The free tier's limit is reached	Add funds to use the marketplace

Provider and price errors

These conditions use HTTP 503. The error code distinguishes a restrictive price ceiling from an unavailable provider:

Code	Meaning	Response
NO_PROVIDER_AVAILABLE	No compatible provider can currently be reached	Retry eligible reads with backoff
NO_PROVIDER_WITHIN_PRICE_LIMIT	No eligible provider is available at or below the configured ceiling	Review the ceiling or wait for supply to change

For example:

{
  "error": {
    "code": "NO_PROVIDER_WITHIN_PRICE_LIMIT",
    "message": "No eligible provider is available within your configured price ceiling."
  }
}

The gateway never raises a ceiling automatically, and you never pay for provider work you did not request. These errors are gateway responses, separate from a node's JSON-RPC error object. See Pricing for the price ceiling.

Payment errors

A 402 means a payment could not be made, and its message says why: nothing is set aside to pay a provider yet, the funds set aside for a provider ran out, or the provider refused the payment, for example from a frozen device. Add funds, or unfreeze the device with your account key. A 429 from a free provider means the free tier's limit is reached; add funds to use the marketplace. See Managing payments and spending.

Direct's own answers never carry a partial or a stale result in place of a node's answer.

WebSocket close codes

A closed WebSocket includes a close code and descriptive reason:

Close code	When
1008	The path names no offering
1013	No compatible provider could be reached: try again later
1011	The provider refused the WebSocket