Rate limit (429) and transient AbortError timeouts on staging relayer — no documented retry guidance

[oooo-o-pixel]

Summary

During iterative testing, I hit both a rate limit error and a separate connection timeout error against the staging relayer. Both were resolved by waiting and retrying, but there's no documentation on expected limits or a recommended retry/backoff strategy.

Errors encountered

1. Rate limit:
2. Transient timeout (separate occasion, unrelated to rate limiting):

This resolved on its own after retrying ~90 seconds later with no code changes.

What's missing from docs

• The 30 weighted-requests/min limit is only visible in the error message itself, not documented ahead of time, so developers can't design around it proactively
• No guidance on what "weighted" means exactly (does remember cost more than recall? does waitForRememberJob count separately?)
• No recommended retry/backoff pattern for either error type
• No indication of how often the transient AbortError timeout should be expected during normal use vs. being a sign of a larger issue

Suggestion

• Document the rate limit numbers and weighting per method in the main SDK docs, not just in the error payload
• Add a recommended retry-with-backoff snippet to the quick-start, since this is likely to affect most developers building conversational/agentic use cases with frequent remember/recall calls
• Clarify expected reliability/timeout characteristics for the staging relayer specifically, since Testnet infra is noted elsewhere as less guaranteed than Mainnet

Impact

Without documentation, it wasn't clear whether these errors indicated a bug in my own implementation or expected, transient relayer behavior — this ambiguity is the main friction point, more than the errors themselves.

[github-actions]

Thank you for opening this issue, a team member will review it shortly.

[ducnmm]

Thanks for the detailed report! The team has received this — we'll add rate limit documentation and retry/backoff guidance to our plan.