Error reference

Invalid JSON returns a JSON-RPC parse error:

{
  "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:

{
  "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:

{
  "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.

{
  "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.

If the code is management_credential_on_rpc, you supplied an sa_ management credential. Use it only on the agent management API. RPC calls require a separate ak_ key. See the agent setup guide.

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:

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.

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:

{
  "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:

{
  "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.

Active PAYG has no request quota and does not return 402 for usage volume. If a PAYG charge fails, PAYG is removed immediately and the account returns to its effective fallback, usually Free. That fallback can then return its normal 402. Resolve every PAYG invoice in Stripe before trying to enroll again. Payment restores eligibility but never silently reactivates PAYG.

{
  "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 active access: it is unknown, revoked, or the account has no effective Free, paid-plan, or PAYG entitlement. Check the key and Billing in the dashboard. Do not retry.

Arc Mainnet (chain ID 5042) also returns 403 to Free accounts and keyless aliases. Use a personal API key on a paid plan or active PAYG; Arc Testnet remains available on Free.

{
  "error": "Arc Mainnet requires a paid plan or active PAYG",
  "code": "paid_network_required",
  "message": "Arc Mainnet requires a paid plan or active PAYG",
  "resolution": "Upgrade to a paid plan or activate PAYG, then retry with your personal API key. Arc Testnet remains available on Free.",
  "documentation_url": "https://solidrpc.io/docs/errors"
}

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:

{
  "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.

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

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.

{
  "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:

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.

A 429 whose body is a JSON-RPC error with code -32005, instead of the envelope above, means SolidRPC is briefly at capacity for large responses. It is not your account limit, it carries Retry-After: 1, and it is never billed:

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32005,
    "message": "capacity exceeded, retry later"
  }
}

Retry after the delay with exponential backoff plus jitter. Inside a batch only the affected calls carry the -32005 error, and the batch keeps HTTP 200 and its usual billing.

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

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

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 503 with upstream_capacity when no upstream connection became free in time, 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.

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 503 with upstream_capacity means the request waited too long for a free upstream connection during a load spike and was refused before it was sent, so no work was done for it. It is temporary and does not indicate a problem with your API key: honor Retry-After and retry with exponential backoff plus jitter. Like every HTTP 5xx, it is never billed.

HTTP/1.1 503 Service Unavailable
Content-Type: application/json; charset=utf-8
Retry-After: 1

{
  "error": "Upstream capacity is temporarily exhausted",
  "code": "upstream_capacity",
  "message": "Upstream capacity is temporarily exhausted",
  "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 only while a security policy change is being applied to the key, which lasts milliseconds:

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

Retry this temporary 503 with backoff. It is never billed and does not indicate an upstream blockchain-node failure. A fault in our own rate-limit or quota infrastructure never produces an error response: the gateway keeps serving your requests on per-instance enforcement until the shared state recovers.