Error Codes

Standard error responses across all FalconQ APIs.

JSON-RPC Errors

The RPC endpoint returns errors as JSON-RPC envelopes with id: null:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32004,
    "message": "Rate limit exceeded"
  },
  "id": null
}

Code	HTTP	Description
-32001	401	Missing API key
-32002	403	Invalid API key — also returned with message `MONTHLY_LIMIT_EXCEEDED` when your monthly quota is used up
-32003	403	Key not authorized for this product
-32004	429	Rate limit exceeded — retry after the `Retry-After` seconds
-32000	503	All upstreams unavailable

Errors returned by the Solana node itself (invalid params, transaction errors, etc.) are passed through unchanged with their original JSON-RPC codes.

REST endpoints (/sol/v1/*) return a JSON envelope instead:

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded"
  }
}

Codes: MISSING_KEY (401), INVALID_KEY (403), UNAUTHORIZED_PRODUCT (403), RATE_LIMITED (429), UPSTREAM_UNAVAILABLE (503).

Successful RPC responses include headers to help you track usage:

x-rate-limit-remaining: 423
x-proxy-region: fra
x-proxy-latency: 2
x-upstream-latency: 38

When rate limited, a Retry-After header indicates seconds until the limit resets.