docs(api): update rate-limits page to the new POLS wire (TRA-879)#199
Merged
Conversation
TRA-878 / PR #438 reworked the rate-limit headers (merged + live on preview, build +438); the existing /docs/api/rate-limits page documented the OLD wire and now contradicts the live API. Bring it in line, verified against the live preview headers and the merged OpenAPI spec descriptions: - X-RateLimit-Limit is now the BURST CEILING (120), not the steady-state (was documented as 60). - X-RateLimit-Remaining now decrements 1:1 from Limit->0 and IS a valid pacing signal — removed the old "don't pace on this header" guidance. - RateLimit-Policy (NEW header) carries the sustained rate as 60;w=60; this is where "60/min" now lives. - X-RateLimit-Reset = seconds until the bucket refills to the ceiling. - Added a verified "what you'll observe" example (fresh bucket: req1 Remaining 119 -> req120 0 -> req121 429 Retry-After 1) and reframed the client-behavior guidance to "pace burst off Remaining, sustained off RateLimit-Policy, back off on 429 + Retry-After." Live wire confirmed on app.preview.trakrf.id: x-ratelimit-limit: 120, ratelimit-policy: 60;w=60, x-ratelimit-remaining decrementing, headers ride a 401. Header wording mirrors the spec's component descriptions.
|
🚀 Preview Deployment Update ✅ This PR has been successfully merged into the preview branch. The preview environment will update shortly at: https://docs.preview.trakrf.id |
Deploying docs with
|
| Latest commit: |
a9eba79
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://f06709e0.docs-4n7.pages.dev |
| Branch Preview URL: | https://docs-tra-879-rate-limits-pol.docs-4n7.pages.dev |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Brings
/docs/api/rate-limitsin line with the rate-limit header rework from TRA-878 / PR #438 (merged + live on preview, build+438). The page documented the old wire and now contradicts the live API; this rewrites it to the new contract. (TRA-879 was originally filed as "add a page" — it was the wrong slug; the page already existed, so this is an update.)What changed (old → new wire)
X-RateLimit-Limit— now the burst ceiling120(was documented as steady-state60).X-RateLimit-Remaining— now decrements 1:1 fromLimit→0and is a valid pacing signal. Removed the old "don't pace on this header" warning and the observability-not-pacing framing.RateLimit-Policy— new header,60;w=60(quota;w=window-seconds) carries the sustained rate; this is where "60/min" now lives.X-RateLimit-Reset— seconds until the bucket refills to the ceiling.Remaining 119→ req1200→ req121429 Retry-After 1) and reframed client guidance to: pace burst offX-RateLimit-Remaining, sustained offRateLimit-Policy, back off on429+Retry-After.429contract:type: rate_limited,Retry-Afterdelta-seconds floored at1,request_idmirrored inX-Request-Id.Verification
app.preview.trakrf.id:x-ratelimit-limit: 120,ratelimit-policy: 60;w=60,x-ratelimit-remainingdecrementing, and the header set rides a401.RateLimitPolicy,XRateLimitLimit,XRateLimitRemaining,XRateLimitReset).pnpm buildpasses (links/anchors resolve).Closes TRA-879.
🤖 Generated with Claude Code