docs: document 429 polling backoff

[scout-relayprotocol]

Implements INT2-1253: Document 429 polling retry backoff

What this changes

• Tells clients polling for status to retry a 429 response with exponential backoff instead of retrying immediately.

How I verified

• git diff origin/main --check passes.
• Reviewed the final branch diff: one sentence changed in one documentation file.

Open questions

• None.

---

🤖 Opened by Scout (autonomous). Ready for human review.
Linear: https://linear.app/relayprotocol/issue/INT2-1253/document-routine-api-rate-limit-upgrades

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
unevenlabs	🟢 Ready	View Preview	Aug 17, 2026, 8:58 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[greptile-apps]

Greptile Summary

This change adds exponential-backoff advice for polling requests that receive a 429 response. The updated sentence also removes existing guidance that helps integrations avoid unnecessary polling before a rate limit is reached: widening intervals, stopping at terminal statuses, and retrieving multiple records with one filtered GET /requests/v3 call. Restore those complementary instructions alongside the new retry advice.

Confidence Score: 4/5

Not ready to merge until the rate-limit page again explains how polling clients can prevent unnecessary requests before receiving a 429 response.

A direct before-and-after documentation check confirmed that the proactive polling and batch-retrieval instructions were removed and replaced with reactive backoff-only advice.

Files Needing Attention: references/api/api_core_concepts/handling-rate-limits.mdx:22 needs the interval, terminal-status, and batch-retrieval guidance restored.

T-Rex Logs

What T-Rex did

• T-Rex executed the rate-limit guidance comparison script to generate evidence for the posted P1 finding.
• T-Rex reviewed the rate-limit guidance check result and captured the base and HEAD documentation guidance for comparison.
• T-Rex validated that the final page omits proactive rate-limit volume-reduction instructions and relies on exponential backoff after a 429 response.
• T-Rex produced proof for a posted P1 finding.

_{Ran code and verified through T-Rex}

Comments Outside Diff (1)

1. General comment

   Restore polling-volume and batch-retrieval guidance removed from rate-limit documentation

   • Bug
     • references/api/api_core_concepts/handling-rate-limits.mdx:22 now advises only exponential backoff after a polling request has already received a 429. The prior sentence instructing readers to widen normal polling intervals, stop at terminal success, failure, and refund statuses, and use GET /requests/v3 for multi-record retrieval is absent from the final page. Readers retaining a polling implementation are consequently not told about the direct request-elimination measures that prevent excess traffic before a 429 occurs.
   • Cause
     • The PR replaces the former combined polling and batch-retrieval operational guidance with a single reactive retry instruction.
   • Fix
     • Keep the exponential-backoff sentence, but restore the proactive polling guidance: widen intervals, stop polling at terminal statuses, and use linked GET /requests/v3 filtered batch retrieval rather than one request per request ID.

   _{Ran code and verified through T-Rex}

_{Reviews (1): Last reviewed commit: "docs: document 429 polling backoff (INT2..." | Re-trigger Greptile}

[greptile-apps]

Proactive polling guidance is missing

This replacement leaves integrations that still poll with advice only for after they have already received a 429. Retain the complementary guidance to widen normal polling intervals, stop polling after success, failure, or refund, and use GET /requests/v3 to retrieve multiple records in one filtered call. Those measures prevent avoidable traffic and rate-limit responses rather than only slowing retries after one occurs.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

Artifacts

Executed rate-limit guidance comparison script

• The authored executable script reads both revisions and asserts that each removed polling and batch-retrieval instruction is present in base and absent in HEAD, showing the tested comparison.

Rate-limit guidance check result

• The executed check exited 0 and reports that base contains while HEAD omits all four tested polling and batch-retrieval instruction fragments, confirming the omission.

Base documentation guidance capture

• The base-revision capture records all tested fragments as present and prints line 22 containing interval widening, terminal-status stopping, and GET /requests/v3 batching guidance, establishing the prior reader-facing behavior.

HEAD documentation guidance capture

• The HEAD capture records every tested prior instruction fragment as absent and prints the replacement backoff-only line 22, establishing the final reader-facing omission.

_{Ran code and verified through T-Rex}