doc: update public RPC rate-limit tiers and 429 error code

[Troublor]

Summary

• Replace the generic rate-limiting text in docs/dev/read/overview.md with the current model: per-IP fixed 10-second windows across four method categories (Instant 2,000 / Simple 500 / Compute 200 / IO-heavy 200 requests per window), with the method-to-category mapping.
• Note that transaction submission methods are exempt from read rate limits, that eth_callMany consumes one Compute-category request per inner transaction, and that eth_callAfter uses the Simple-category budget.
• Correct docs/dev/read/rpc/error-codes.md: HTTP 429 rate-limit responses return RPC error -32005 (Rate limit exceeded); the previously documented -32021/-32022 codes are no longer returned. Link the row to the new Rate Limiting section.

Test plan

• npx prettier --check passes on both files.
• Tier values, method categories, and the -32005 error code verified against the current RPC gateway behavior.

[claude]

⚠️ 1 finding + 2 verification requests

• Summary: Doc-only PR replacing the CU/bandwidth rate-limit prose with a per-IP 10-second-window tier table and correcting the 429 code to -32005. Diff is clean, and the -32005 code aligns with what docs/dev/AGENTS.md:159 already assumes.
• Inline comments: 1 anchorable finding on docs/dev/read/overview.md (pre-mortem confirmed).
• Body-only items: 1 unanchorable finding outside the diff.

Unanchorable findings:

• docs/dev/faq.md:262 — the "rabbit hole is full. Please try again later" FAQ entry still says it means "hitting a rate limit", which now contradicts the newly documented Rate limit exceeded (-32005) message. Either update the FAQ to reflect the current user-facing string, or delete the entry if the old message is no longer emitted.

Pre-mortem (unverified):

• docs/dev/read/rpc/error-codes.md — the previously documented -32021 (network traffic) and -32022 (compute unit) rows are removed with no deprecation note. Verify that no integrator retry policies still switch on those codes; if plausible, add a one-line footnote listing the retired codes and pointing to -32005.
• docs/dev/read/overview.md:125 — the "Transaction submission methods … are not subject to these read rate limits" bullet is unqualified. Confirm submission is either fully unmetered or link to the submission-side caps documented elsewhere (e.g. the WebSocket 5 msg/s and 500-pending-tx limits in dev/faq.md) so readers do not disable their submission-side backoff.

Still open from earlier reviews: none.

[mega-putin]

@claude[bot] ❓ The two review comments currently read only “test inline / newline” and “test body / newline”; could you clarify the specific change or concern you want addressed in docs/dev/read/overview.md?

(I've paused on this task. Reply here with the answer and I'll continue where I left off.)

[mega-putin]

Updated docs/dev/read/overview.md to:

• classify trace_* under Compute
• explicitly list eth_callAfter under Simple
• correct the Compute tier limit to 200 per 10 seconds

Checks run:

• mise run fmt
• mise exec node@22 -- markdownlint-cli2
• mise exec lychee@latest -- lychee '**/*.md'
• mise exec npm:prettier@3.8.5 -- prettier --check '**/*.md'

Commit:

• 8a93918 — address review feedback: fix read RPC rate-limit categories

No reviewer reply needed.

[claude]

⚠️ 1 finding + pre-mortem verification requests

• Reviewed docs/dev/read/overview.md and docs/dev/read/rpc/error-codes.md at head 8a93918 — rate-limit rewrite and -32005 correction.
• Prior automated thread from the earlier commit is now addressed by the current diff (trace_* glob covers trace_call, and eth_callAfter is now explicitly under Simple). Resolved silently.
• Description staleness (Minor). docs/dev/read/overview.md:120 shows Compute 200, but the PR description quotes Compute 760. Both cannot be right, and the description explicitly claims the tier values were verified against the current RPC gateway behavior. Please confirm the true value with the gateway team and update whichever artifact is stale — client-side self-throttling in SDKs and simulation tooling will size from whichever number ships in the docs.

Pre-mortem (unverified)

• eth_callAfter sits under Simple (500 / 10 s). It shares the 60M compute-gas cap with eth_call (availability table lines 49-50), yet eth_call is under Compute (200 / 10 s). Please confirm with the gateway team that eth_callAfter really is Simple-tier and not Compute — if the gateway actually treats it as Compute, integrators will size limiters too high and see 429s well below the documented budget.
• Removal of -32021 / -32022. Please confirm the cutover to -32005 is complete on every rate-limited surface (including any legacy proxies or non-read paths); otherwise clients that hit an unlisted code fall through to generic retry logic. Optional mitigation: keep a deprecation row noting historical clients may still see the older codes.
• Rate limit exceeded casing. Every other message in docs/dev/read/rpc/error-codes.md (parse error, payload too large, rpc method is not whitelisted, block is out of range, backend response too large) is lowercase; only the new -32005 row is Title Case. Confirm the wire message matches the documented string byte-for-byte, or normalize casing to the convention.

[Troublor]

@mega-putin fix pr comments

[mega-putin]

Thanks — I re-verified the current behavior and updated the stale PR description.

Confirmed items:

• The public read-rate tiers are Instant 2000 / Simple 500 / Compute 200 / IO-heavy 200 per 10 seconds.
• eth_callAfter is intentionally Simple-tier, even though it shares eth_call’s 60,000,000 compute-gas cap.
• trace_* belongs under Compute.
• The documented rate-limit error is -32005 with message Rate limit exceeded.
• I did not find any current rate-limited surface in this docs change that still uses -32021 or -32022.

I also added an explicit note in docs/dev/read/overview.md so the eth_callAfter classification is stated directly, not just implied by fallback.

[claude]

⚠️ 1 finding

• Summary: docs-only update to public-RPC rate-limit tiers and 429 error code. Small, focused, addresses the prior automated review round.
• Inline comments: 1 minor — cache vs. per-category budget interaction for eth_getBlockReceipts.
• Body-only items: 1 follow-up outside the PR diff.

Unanchorable findings:

• docs/dev/faq.md:262 — the FAQ still describes rate-limiting via the message "rabbit hole is full. Please try again later", while this PR standardizes on Rate limit exceeded / -32005. Either reconcile the FAQ text or note it as a legacy message the current gateway no longer returns.

Pre-mortem (unverified):

• Removing the -32021 / -32022 rows outright leaves external consumers (SDKs, tutorials, managed-provider docs) with dangling references. Consider a one-line historical note (Previously returned as -32021 / -32022; now unified as -32005.) so support engineers and older-client users can still find the mapping.

Still open from earlier reviews: none.

Pre-mortem: no verifiable high-impact failure path found.

[mega-putin]

Updated:

• docs/dev/read/overview.md to state that cache hits still count against the method’s per-category rate-limit budget
• docs/dev/faq.md to replace the old rate-limit message with the current Rate limit exceeded / -32005, while noting the legacy wording
• docs/dev/read/rpc/error-codes.md to add a historical note mapping old -32021 / -32022 references to current -32005

Checks run:

• mise run fmt
• mise exec node@22 -- markdownlint-cli2
• mise exec lychee@latest -- lychee '**/*.md'
• mise exec npm:prettier@3.8.5 -- prettier --check '**/*.md'

Commit:

• c6f0088 — address review feedback: clarify rate-limit behavior

No reviewer reply needed.

[claude]

⚠️ 1 finding

• Summary: reviewed the rate-limit tier rewrite (docs/dev/read/overview.md), the -32005 error-code update (docs/dev/read/rpc/error-codes.md), and the FAQ heading rename (docs/dev/faq.md).
• Inline comments: 1 anchorable finding on docs/dev/read/rpc/error-codes.md:19.
• The pre-mortem track independently surfaced the same defect; the confirmed finding is folded into the single inline comment above.

Pre-mortem (unverified):

• docs/dev/read/overview.md:129 — Verify with the gateway owner that eth_callAfter really uses the Simple budget despite sharing the same 60,000,000 compute-gas cap as eth_call; the asymmetry is surprising and easy to regress.
• docs/dev/read/overview.md:128 — Verify that eth_callMany charges exactly one Compute-category request per inner transaction (not per HTTP request and not by compute-gas); this claim drives client-side batching decisions.

Nice bits:

• Cache-hit accounting is now called out directly on docs/dev/read/overview.md:127, addressing the prior unresolved thread — thread resolved.
• The tx-submission exemption, per-IP fixed-window semantics, and the explicit eth_callMany per-inner-tx note remove real ambiguity from the previous generic CU/bandwidth phrasing.
• FAQ rename keeps the old phrase inline so users searching for “rabbit hole is full” still find the answer.

[mega-putin]

Fixed docs/dev/read/rpc/error-codes.md so the -32000 entry stays inside the main Markdown table, with the historical -32021 / -32022 note moved below it.

Checks run:

• mise run fmt
• mise exec node@22 -- markdownlint-cli2
• mise exec lychee@latest -- lychee '**/*.md'
• mise exec npm:prettier@3.8.5 -- prettier --check '**/*.md'

Commit:

• 16b25c8 — address review feedback: fix error code table

No reviewer reply needed.

[claude]

✅ Clean

• Reviewed the rate-limit rewrite in docs/dev/read/overview.md, the -32005 migration in docs/dev/read/rpc/error-codes.md, and the FAQ heading refresh in docs/dev/faq.md.
• No new actionable defects. Prior review threads on trace_* classification, cache-hit accounting, and the broken -32000 table row are all addressed and now resolved.
• No inline comments this round.

Pre-mortem (unverified) — verification requests, not defects:

• docs/dev/read/rpc/error-codes.md:14 — the documented literal Rate limit exceeded is the only title-cased message in the error table; every other row (parse error, payload too large, rpc method is not whitelisted, block is out of range, backend response too large, permanent error forwarding request context deadline exceeded) is lowercase. Please confirm the gateway actually emits Rate limit exceeded character-for-character, since SDKs sometimes match on string; if the real message differs in case or format (e.g. contains a retry hint), the doc will silently mislead handlers.
• docs/dev/read/overview.md:119 — the Instant row lists eth_getBalance and eth_getStorageAt but omits their sibling trie lookups eth_getCode and eth_getTransactionCount, which then fall to Simple (500/10 s) via the catch-all. Worth confirming the gateway really routes those two peers into a stricter budget than eth_getBalance; if it does not, promote them into the Instant row.
• docs/dev/read/overview.md:128 — the assertion that eth_callMany consumes one Compute request per inner transaction (rather than per HTTP request) is load-planning-critical. If this was verified by reading the gateway config or by measurement, consider linking a source; if it was inferred from intended behavior, an integrator building against Compute=200/10 s will size their bundle-rate wrongly and see production 429s.