QuickNode Rate-Limit Control
Overview
Treat account-plan ceilings, IP limits, and operator-configured method limits as separate controls. QuickNode exposes distinct JSON-RPC errors for per-second, per-minute, and method limits; an HTTP status alone is not sufficient diagnosis.
Prerequisites
- Endpoint ID, plan, chain, network, and affected method
- A redacted error sample with HTTP and JSON-RPC fields
- Authorized dashboard, Admin API, or
qnread access
Authentication
Authenticate qn interactively with qn auth login and verify the intended account with qn auth whoami. For direct Admin API inspection, inject a separate account API key as the x-api-key header. Endpoint tokens in URLs or x-token headers authenticate RPC traffic but do not replace control-plane credentials.
Instructions
Step 1: Classify the signal
Use Read and Grep to find the first complete redacted response. Preserve QuickNode codes such as -32007 per-second, -32008 per-minute, and -32011 method limit. Separate client timeouts and chain-node errors.
Step 2: Read the configured limits
Use Bash(qn:*) to inspect endpoint and method-rate settings through authenticated read commands. If the CLI version lacks the required view, use the dashboard or documented Admin API rather than guessing a number.
Step 3: Measure demand
Group requests by endpoint, token, source IP, method, and interval. Distinguish HTTP calls from WebSocket subscription creation; subscription responses do not count like new requests.
Step 4: Choose the control
Reduce concurrency, coalesce duplicate reads, cache immutable results, or set a method limit that protects expensive calls. Raising a plan limit is a capacity decision, not the first retry strategy.
Step 5: Implement bounded retry
Use Write or Edit to retry only idempotent reads and only recognized transient limit responses. Apply jitter, cap attempts and elapsed time, and honor a provider delay header when documented. Never automatically replay transaction submissions.
Step 6: Prove under load
Test below and above the intended threshold in a non-production endpoint. Confirm the expected code, bounded client behavior, recovery, and absence of synchronized retry bursts.
Tool Discipline
Use Read and Grep for error and demand discovery, Bash(qn:*) for authenticated read-only control-plane inspection, and Write/Edit for bounded retry or throttling code. Require explicit approval before changing production limits.
Output
- Limit-layer classification
- Measured method and interval demand
- Bounded client-control change
- Before/after load receipt and rollback threshold
Examples
A single trace method hits -32011 while ordinary reads succeed. The operator caps that method and queues callers instead of applying a global retry loop to every RPC request.
Error Handling
| Failure | Response |
|---|---|
-32007 | Reduce per-second bursts or review plan capacity |
-32008 | Flatten longer-window demand and inspect batch jobs |
-32011 | Inspect the endpoint's method-specific rule |
| Transaction submission is limited | Reconcile transaction identity before any manual retry |