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.

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.

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: ..."
  }
}

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

Authentication errors

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.