429 Too Many Requests error handling in Polygon RPC provider

Direct Answer

Polygon’s RPC layer should provide a minimal, configurable retry interface that respects the provider’s rate‑limit boundaries. The provider can expose a simple back‑off policy (e.g., exponential with jitter) and a maximum retry count, while leaving fine‑grained control—such as per‑endpoint rotation or custom jitter—to client libraries.

Why a built‑in policy matters

• Prevents accidental request avalanches that can trigger further 429s.
• Standardises behaviour across dApps, reducing inconsistent error handling.
• Allows the provider to adjust limits or offer higher tiers without breaking existing clients.

When to retry a failed request

Retries should only occur for transient failures that are likely to succeed after a short wait. Criteria include:

• HTTP 429 with a Retry-After header – honour the specified wait time.
• HTTP 429 without Retry-After – apply exponential back‑off starting at 1–2 s, capped at a configured maximum (e.g., 30 s).
• Network‑level timeouts or 5xx server errors – treat them as transient and retry up to a configured limit.
• Requests that are idempotent (e.g., read‑only JSON‑RPC calls) – safe to retry; non‑idempotent writes should not be retried automatically.

Implementing a safe back‑off strategy

1. Read the Retry-After header. If present, wait that number of seconds or until the specified HTTP date.
2. Apply exponential back‑off with jitter. Example: wait = min(maxWait, base * 2**attempt + random(0, 1)) where base is 1 s and maxWait is 30 s.
3. Respect the provider’s per‑minute quota. Track requests per IP/account and do not exceed the documented threshold during back‑off windows.
4. Limit total retries. Expose a configurable maxRetries (default 3) so that clients can opt‑out of aggressive retrying.

Configurable options for client libraries

• retryPolicy: choose between none, exponential, or a custom callback.
• maxRetries: override the default retry count.
• backOffBase & backOffMax: adjust the back‑off window.
• perEndpointLimits: expose per‑endpoint rate limits so clients can rotate endpoints within safe bounds.

What the client should do

Client libraries should:

• Detect 429 responses and invoke the provider’s retry policy.
• Avoid retrying non‑idempotent write calls unless the application explicitly confirms it is safe.
• Log each retry attempt with the wait duration for observability.

Missing diagnostic detail

Does your current RPC endpoint return a Retry-After header with every 429? If not, the provider might be using a fixed back‑off window, which could affect how you tune your client’s retry logic.

Summary

Providing a lightweight, configurable retry interface in the Polygon RPC layer—respecting Retry-After, using exponential back‑off, and limiting retries—offers the most robust path forward. This approach keeps the provider’s rate‑limit guarantees intact while giving client libraries the flexibility to implement advanced strategies such as endpoint rotation or custom jitter.