RPC operator referenceHTTPS · JSON-RPC 2.0

Error reference

Machine-readable gateway and JSON-RPC errors, their billing behavior, and the next action to take.

Three sources, two response shapes

HTTP-layer rejections generated by the authenticated gateway use a top-level JSON envelope. error is the backward-compatible short label, code is a stable machine-readable string,message explains the failure, resolution gives the next action, and documentation_url points to the controlling reference. Quota and limit errors can add fields such as used, limit, or requiredTokens.

JSON-RPC protocol and gateway-policy failures keep the JSON-RPC 2.0 shape. Their numeric code and message live in error, while SolidRPC's actionable resolution and documentation_url live in error.data. Errors returned by a blockchain node pass through unchanged and may not contain those two guidance fields.

Gateway rejections never reach a node and are never billed. Proxy or upstream HTTP 5xx failures are also never billed. A node-returned JSON-RPC error normally arrives with HTTP 200 and consumes one response unit because the node performed the method call. Check the HTTP status first, then inspect either the top-level string code or the numeric error.code. The complete request and response contract is published in the SolidRPC OpenAPI 3.1 contract.

Gateway errors

400 malformed JSON-RPC request

Invalid JSON returns a JSON-RPC parse error:

Request example

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32700,
    "message": "Parse error",
    "data": {
      "resolution": "Send syntactically valid JSON with Content-Type: application/json.",
      "documentation_url": "https://solidrpc.io/docs/errors"
    }
  }
}

Empty batches, objects without a method, and batches without any valid method return an invalid-request error:

Request example

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32600,
    "message": "Invalid Request",
    "data": {
      "resolution": "Send a JSON-RPC 2.0 object with a non-empty method, params, and request id.",
      "documentation_url": "https://solidrpc.io/docs/errors"
    }
  }
}

On the clean /evm/{chainId} route, sending both X-API-Key and Authorization: Bearer YOUR_API_KEY is ambiguous and returns:

Request example

{
  "error": "Conflicting API key sources",
  "code": "conflicting_api_key_sources",
  "message": "Conflicting API key sources",
  "resolution": "Send either Authorization: Bearer YOUR_API_KEY or X-API-Key: YOUR_API_KEY, not both.",
  "documentation_url": "https://solidrpc.io/docs/errors"
}

This check runs before authentication and rate limiting, so a conflicting request consumes nothing. Pick one transport.

Malformed JSON-RPC requests consume one rate-limit token to prevent abuse, but they never consume quota or appear as billed usage. Valid JSON is accepted even when the content type is missing or not application/json, although clients should continue sending Content-Type: application/json. Payloads over 5 MB return HTTP 413 and are also free.

401 missing or invalid authentication

Request example

{
  "error": "Missing or invalid API key",
  "code": "invalid_api_key",
  "message": "Missing or invalid API key",
  "resolution": "Send a valid SolidRPC API key using a documented URL or header authentication form.",
  "documentation_url": "https://solidrpc.io/docs/errors"
}

The URL key is absent or malformed, or the clean endpoint has no valid Bearer API key or X-API-Key header. Check either https://rpc.solidrpc.io/YOUR_API_KEY/evm/{chainId} or https://rpc.solidrpc.io/evm/{chainId} with one supported API-key header. Do not retry; fix the credential.

When a key requires JWT authentication, a missing, malformed, expired, or otherwise invalid Bearer token returns the same generic JWT error with the standard challenge header:

Request example

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer

{
  "error": "Missing or invalid JWT",
  "code": "invalid_customer_jwt",
  "message": "Missing or invalid JWT",
  "resolution": "Send a valid customer-signed Bearer JWT that satisfies the API key's configured issuer, audience, lifetime, and scopes.",
  "documentation_url": "https://solidrpc.io/docs/errors"
}

A JWT-required key must use the URL-key form plus a Bearer JWT, or X-API-Key: YOUR_API_KEY plus the Bearer JWT. A Bearer API key alone cannot satisfy both credentials.

Check the signature, server-generated kid, fixed audience, issuer, and numeric time claims. See API key security.

402 quota exceeded

You used all response units in your plan, and overage billing is not enabled. Further RPC calls are blocked at the quota unless overage billing is enabled. On a monthly (paid) plan:

Request example

{
  "error": "Monthly response quota exceeded",
  "used": 10000000,
  "limit": 10000000,
  "code": "monthly_quota_exceeded",
  "message": "You have used all responses included in your plan. Upgrade to continue.",
  "resolution": "Wait for the billing-period reset, upgrade the plan, or enable overage billing when eligible.",
  "documentation_url": "https://solidrpc.io/docs/pricing"
}

On the Free plan the quota is daily:

Request example

{
  "error": "Daily response quota exceeded",
  "used": 10000,
  "limit": 10000,
  "window": "day",
  "code": "daily_quota_exceeded",
  "message": "You've used all responses included in your plan for today. Your quota resets at 00:00 UTC. Upgrade to a paid plan for a monthly quota and higher limits.",
  "resolution": "Wait until 00:00 UTC, upgrade the plan, or use an eligible paid plan with overage enabled.",
  "documentation_url": "https://solidrpc.io/docs/pricing"
}

Do not retry a 402, it stays a 402 until your quota resets (00:00 UTC on Free, your billing date on paid plans), you upgrade, or you enable overage.

403 invalid key, subscription, or policy denial

Request example

{
  "error": "Invalid API key or inactive subscription",
  "code": "api_key_forbidden",
  "message": "Invalid API key or inactive subscription",
  "resolution": "Check that the API key is active and belongs to an account with an active subscription.",
  "documentation_url": "https://solidrpc.io/docs/errors"
}

The key looks valid but doesn't resolve to an active account: it is unknown, revoked, or the account has no active subscription. Check the key in the dashboard. Do not retry.

A valid API key and JWT can also be denied when the verified source, chain, or any method in the request is outside the effective key/token policy:

Request example

{
  "error": "Request denied by API key policy",
  "reason": "method_denied",
  "code": "api_key_policy_denied",
  "message": "Request denied by API key policy",
  "resolution": "Use a source, chain, and method allowed by the API key and delegated token policy.",
  "documentation_url": "https://solidrpc.io/docs/errors"
}

The bounded reason is one of route_denied, source_unverified, source_denied, chain_denied, or method_denied. Policy denials never consume quota or billed usage.

404 unknown route and 405 wrong HTTP method

Unknown gateway paths return a structured JSON 404 instead of HTML. Its documentation_url points directly to the machine-readable OpenAPI contract:

Request example

HTTP/1.1 404 Not Found

{
  "error": "API route not found",
  "code": "api_route_not_found",
  "message": "API route not found",
  "resolution": "Use a documented POST endpoint from the SolidRPC OpenAPI contract.",
  "documentation_url": "https://solidrpc.io/openapi.json"
}

The clean /evm/{chainId} route accepts only HTTPS POST. Other methods return HTTP 405, set Allow: POST, and use the same gateway envelope with code method_not_allowed. An unavailable chain on the keyless public route is different: it returns a JSON-RPC error whose guidance remains inside error.data.

429 rate limit exceeded

Request example

{
  "error": "Rate limit exceeded",
  "requiredTokens": 1,
  "availableTokens": 0,
  "code": "rate_limit_exceeded",
  "message": "Rate limit exceeded",
  "resolution": "Wait for Retry-After seconds, then retry with exponential backoff and jitter.",
  "documentation_url": "https://solidrpc.io/docs/rate-limits"
}

Your account's token bucket is empty (batches need one token per method call, all at once). A recoverable 429 includes a Retry-After delay:

Request example

HTTP/1.1 429 Too Many Requests
Retry-After: 1
X-RateLimit-Limit: 120
X-RateLimit-Burst: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 5

Wait for that delay, then retry with exponential backoff plus jitter. If the batch exceeds X-RateLimit-Burst, the header is omitted because the batch must be split. See rate limits. Never billed.

Repeated invalid JWT verification attempts use a separate abuse bucket and can return:

Request example

HTTP/1.1 429 Too Many Requests
Retry-After: 1

{
  "error": "JWT verification rate limit exceeded",
  "code": "jwt_verification_rate_limit_exceeded",
  "message": "JWT verification rate limit exceeded",
  "resolution": "Wait for Retry-After seconds before submitting another JWT verification attempt.",
  "documentation_url": "https://solidrpc.io/docs/api-key-security"
}

5xx temporary service, upstream, or proxy transport failure

When the gateway cannot complete its proxy connection, it returns the structured gateway envelope: HTTP 502 with upstream_bad_gateway for an invalid upstream HTTP response, HTTP 504 with upstream_timeout for a reset, DNS, connection, or timeout failure, and HTTP 500 with proxy_internal_error for an unclassified internal proxy failure. These responses include Retry-After: 1and never echo the requested host, path, or API key.

Request example

HTTP/1.1 504 Gateway Timeout
Content-Type: application/json; charset=utf-8
Retry-After: 1

{
  "error": "Upstream request timed out",
  "code": "upstream_timeout",
  "message": "Upstream request timed out",
  "resolution": "Wait one second, then retry with exponential backoff. Contact SolidRPC support if the error persists.",
  "documentation_url": "https://solidrpc.io/docs/errors"
}

A server that successfully returns its own HTTP 5xx response is different: the proxy passes that status and body through unchanged. That upstream body can be JSON-RPC or another JSON error shape and is not guaranteed to contain SolidRPC's resolution or documentation_url. A 504 can also mean the upstream method budget was exhausted, 30 seconds for standard methods and 45 seconds for trace/debug (see tracing).

Every HTTP 5xx is free: its quota reservation is refunded and it cannot generate overage, although it remains visible in error and latency analytics. Rate-limit tokens are not refunded, which prevents retry storms. Honor Retry-After when present and retry with exponential backoff plus jitter. A heavy trace that repeatedly returns 504 needs a narrower query, not unlimited retries.

Advanced key policies fail closed while security state is changing or a hard delegated limit cannot be enforced:

Request example

HTTP/1.1 503 Service Unavailable
Retry-After: 1

{
  "error": "API key security policy is being updated",
  "code": "api_key_policy_updating",
  "message": "API key security policy is being updated",
  "resolution": "Wait for Retry-After seconds, then retry the same request.",
  "documentation_url": "https://solidrpc.io/docs/errors"
}

Request example

{
  "error": "Rate limit service unavailable",
  "code": "rate_limit_service_unavailable",
  "message": "Rate limit service unavailable",
  "resolution": "Wait for Retry-After seconds, then retry the same request.",
  "documentation_url": "https://solidrpc.io/docs/rate-limits"
}

Retry these temporary 503 responses with backoff. They are never billed and do not indicate an upstream blockchain-node failure.

Blocked methods

Methods on the gateway denylist (node and consensus control, including txpool_*, see the method policy) return HTTP 200 with a JSON-RPC -32601 error and are never billed. The request ID is preserved for a single call, and SolidRPC guidance is placed in error.data:

Request example

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "method admin_peers is not supported",
    "data": {
      "resolution": "Use a supported read, trace, or debug method that does not control the node or consensus layer.",
      "documentation_url": "https://solidrpc.io/docs/errors"
    }
  }
}

Node-passthrough errors

Execution reverts, -32602 (invalid params), -32000-range client errors, and a node's own -32601 for methods its client doesn't implement all pass through unchanged with HTTP 200. These method calls reached the nodes and did the work, so each consumes 1 response unit like any other billable call. Treat a node's error.data as method- and client-specific; unlike gateway-produced JSON-RPC errors, it is not guaranteed to include resolution or documentation_url.

Batch semantics

A batch containing any blocked method is rejected whole: one error object with id: null, nothing executed, nothing billed.
Gateway errors: 400, 401, 402, 403, 413, 429, apply to the whole batch.
An upstream HTTP 5xx applies to the whole batch and bills none of its entries.
A partially invalid batch reaches the node, only entries with a valid method consume rate-limit and quota units.
Node-level errors are per-entry: one revert doesn't fail the rest of the batch, and every entry that reached the nodes is billed.

Quick reference

Status	Meaning	Billed	Retry?
200 (result)	Successful response	Yes	—
200 + -32601 (blocked)	Method blocked by gateway policy	No	No
200 + JSON-RPC error	Node-level error (revert, bad params, …)	Yes	Depends on the error
400	Invalid JSON/JSON-RPC or conflicting API-key headers	No	No, fix the request
401	Missing or malformed API key, or missing/invalid required JWT	No	No, fix the key
402	Quota exceeded, overage not enabled	No	No, upgrade, enable overage, or wait for reset
403	Unknown/revoked key, inactive subscription, or policy denial	No	No
404	Unknown API route or unavailable public chain	No	No, use a documented route or chain ID
405	The clean RPC route received a method other than POST	No	No, send HTTPS POST
413	Request body exceeds 5 MB	No	No, reduce the payload
429	Rate limit exceeded	No	Yes, with backoff
500–599	Temporary security-state, rate-limit, upstream, or proxy transport failure	No	Yes, with backoff