quicknode-rate-limits

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 qn read 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

About this skill