Operations

Errors and retries

Identify the failed layer and decide whether to fix, wait, or check the transaction outcome.

Check HTTP and JSON-RPC

Check the HTTP status and each JSON-RPC response’s error field. An HTTP 200 can still contain a method error or a batch with failed items. Keep the request ID so you can match every result.

Example invalid-key response

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32001,
    "message": "Invalid or revoked key"
  }
}

Common responses and next steps

HTTP status	What to do
400 · Invalid request	Check JSON syntax, the method allowlist, parameters, and a string or integer id. Notifications are unsupported.
401 · Invalid credentials	Check your Relay key, authentication format, and whether the key was revoked.
402 · Allowance exhausted	Check available credits and the timing of your next paid period.
403 · Access inactive	Check the active paid Mainnet period, account access, and whether this key fits the purchased key limit.
413 · Request too large	Reduce the request body to at most 64 KiB.
415 · Unsupported content type	Send Content-Type: application/json.
429 · Limit reached	Reduce concurrency, honor Retry-After, and check request-rate and available-credit limits.
502 · Upstream request failed	Inspect the JSON-RPC result. Retry safe reads with bounded backoff; check transaction status before resubmitting.
503 · Service unavailable	Check for inactive service or unavailable capacity. Retry safe reads later with bounded backoff.

Common JSON-RPC codes include -32700 for invalid JSON, -32600 for an invalid request, and -32601 for an unsupported method.

Retry with a known outcome

For safe reads, use a bounded retry count and increasing delays with jitter. Honor Retry-After when present. Correct authentication and request-shape errors before retrying.

Relay may use another eligible connection after a conclusive upstream rejection of a non-submission request. Successful batch items and uncertain outcomes are not automatically replayed. sendTransaction and sendBundle are never automatically retried by Relay.