Errors and troubleshooting

HTTP status codes, 429 rate-limit handling with Retry-After, JSON-RPC error codes, and backoff guidance for rpc edge.

Every integration hits errors - a bad key, a rate limit, a transient upstream. This page covers the error responses rpc edge returns and how a well-behaved client should handle them.

HTTP status codes

The RPC gateway uses standard HTTP status codes before a JSON-RPC body is even parsed.

Status	Meaning	Client action
`200`	Request accepted; check the JSON-RPC body for a `result` or `error`.	Parse the body.
`401`	Missing or invalid API key.	Fix auth; do not retry as-is.
`403`	Key valid but the method or resource is not enabled on your plan.	Use an enabled method, or upgrade.
`429`	Rate limit exceeded (RPS or account-read units).	Back off and retry (below).
`5xx`	Transient gateway or upstream error.	Retry with backoff.

Handling 429

A 429 means you exceeded your plan's RPS or account-read unit budget. When present, honor the Retry-After response header (seconds); otherwise use exponential backoff with jitter.

backoff.ts

async function rpc(body: unknown, tries = 5): Promise<Response> {
  const ENDPOINT = "https://rpc.rpcedge.com?key=YOUR_UUID_KEY";
  for (let attempt = 0; attempt < tries; attempt++) {
    const res = await fetch(ENDPOINT, {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify(body),
    });
    if (res.status !== 429 && res.status < 500) return res;
 
    const retryAfter = Number(res.headers.get("retry-after"));
    const waitMs = Number.isFinite(retryAfter) && retryAfter > 0
      ? retryAfter * 1000
      : Math.min(2 ** attempt * 250, 8000) + Math.random() * 250; // backoff + jitter
    await new Promise((r) => setTimeout(r, waitMs));
  }
  throw new Error("rpc: exhausted retries");
}

JSON-RPC errors

When the HTTP status is 200 but the request failed, the body carries a standard JSON-RPC error object, with your request id preserved:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params: ..."
  }
}

Code	Meaning	Typical cause
`-32700`	Parse error	Malformed JSON body.
`-32600`	Invalid request	Not a valid JSON-RPC request object.
`-32601`	Method not found	Method disabled on your plan or misspelled - see rate limits.
`-32602`	Invalid params	Wrong parameter shape or types.
`-32603`	Internal error	Transient; retry with backoff.
`-32002`	Transaction simulation failed	Inspect `data.logs` in the error for the on-chain reason.

Always branch on the JSON-RPC error field even on a 200 response - a successful HTTP call can still carry a method-level error.

A 401 means the key is missing or wrong. Check that you are sending the key in one of the supported forms (?key=, x-api-key, x-token, or Authorization: Bearer) and that it has no surrounding whitespace. Keys are UUIDs; a truncated or url-encoded key fails auth.

gRPC stream errors

Yellowstone gRPC streams are long-lived and can drop on network blips, server restarts, or if you cannot drain the stream fast enough and it backs up. Treat a disconnect as normal operations:

Reconnect with backoff and re-send your SubscribeRequest.
Track the last processed slot so you can detect a gap on reconnect.
Keep filters narrow - an over-broad subscription you cannot drain will disconnect under load. See subscribe.

Errors and troubleshooting

HTTP status codes

Handling 429

JSON-RPC errors

Authentication errors

gRPC stream errors