Overview
Preserve HTTP status, JSON-RPC code, chain error, method, network, and request identifier as separate facts. Do not treat every -32000 family response as retryable or overwrite a contract revert with a provider diagnosis.
Prerequisites
- A redacted failing request and response
- Endpoint ID, chain, network, protocol, and client version
- The expected method contract and a nearby successful request if available
Instructions
Step 1: Capture the first failure
Use Read and Grep to locate the earliest complete failure before wrapper retries transform it. Redact endpoint tokens, API keys, signed transactions, addresses when sensitive, and request bodies not needed for diagnosis.
Step 2: Assign the layer
Classify DNS/TLS/timeout, HTTP authentication, QuickNode infrastructure, endpoint security, chain-node, smart-contract, or client-decoding failure. Keep nested causes intact.
Step 3: Interpret QuickNode codes
Recognize -32007 per-second limit, -32008 per-minute limit, -32011 method limit, -32604 empty or unsupported method, and -32611 endpoint security-filter rejection. Verify other codes against the chain-specific reference.
Step 4: Inspect control-plane evidence
Use Bash(qn:*) for authenticated endpoint, metrics, or permitted error-log reads. Admin API endpoint logs are plan-gated; absence of access is not proof that no request reached QuickNode.
Step 5: Run one discriminating test
Compare a supported read method on the same endpoint, the same method with corrected parameters, or the same request in a non-production environment. Avoid retries that could resubmit a signed transaction.
Step 6: Route ownership
Assign the finding to credential owner, endpoint-security owner, capacity owner, chain integration, contract developer, or QuickNode support. Include only sanitized evidence and a reversible next action.
Tool Discipline
Use Read and Grep for local evidence and Bash(qn:*) only for read-only account inspection. This diagnostic workflow does not edit code, rotate credentials, change limits, or replay writes.
Output
- Layered failure classification
- Preserved HTTP, RPC, and chain facts
- One discriminating test result
- Named owner and safe next action
Examples
HTTP succeeds but JSON-RPC returns -32611; a simple allowed method works. Route the issue to endpoint filter configuration instead of increasing capacity or retrying.
Error Handling
| Signal | Interpretation guardrail |
|---|---|
| 401 or 403 | Check credential type and security policy |
| 429 plus RPC code | Preserve both; use the RPC code to identify the limit |
| Contract revert | Decode against ABI and chain state; do not auto-retry |
| Method unsupported | Verify chain, network, add-on, and current method reference |