docs: 429 stream error now dispatches StreamError event - #506
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
📝 WalkthroughWalkthroughThe documentation now states that HTTP 429 stream errors emit Changes429 stream-error behavior
Estimated code review effort: 1 (Trivial) | ~5 minutes Possibly related PRs
Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
| Filename | Overview |
|---|---|
| advanced/websocket-handling.mdx | Updates the 429 stream-error event and backoff documentation consistently. |
| api/client.mdx | Documents the StreamError followed by Disconnected event sequence for 429 responses. |
| concepts/events.mdx | Adds 429 to the documented StreamError emission behavior and generalizes the usage example. |
Reviews (5): Last reviewed commit: "docs: merge StreamError emission cases i..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
concepts/events.mdx (1)
484-488: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick winCorrect the contradictory
StreamErrornote.The note says recognized codes emit specific events instead of
StreamError, but the next row documents429asStreamError. Readers could ignore the429event. Change the introductory sentence so it describes explicit handling without excludingStreamError.Proposed wording
-Recognized stream error codes emit specific events instead of `StreamError`: +Specific stream error codes have the following event behavior:🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@concepts/events.mdx` around lines 484 - 488, Update the introductory sentence in the recognized stream error codes note to describe explicit event handling without stating that these codes emit events instead of StreamError; preserve the existing 401, 409, and 429 mappings unchanged.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@advanced/websocket-handling.mdx`:
- Line 1122: Rewrite the rate-limit backoff sentence in active voice by making
the client the subject that increments the backoff counter by 5 before the
normal increment; preserve the existing behavior and surrounding explanation.
In `@api/client.mdx`:
- Around line 512-513: Update the Event::StreamError reference in the client
documentation to use the documented tuple-variant pattern,
Event::StreamError(err), matching the StreamError(StreamError) definition in
concepts/events.mdx. Keep the surrounding explanation of code 429 behavior
unchanged.
In `@concepts/events.mdx`:
- Line 466: Update the emission description around the “Emitted” text so it
states that the client reports a 429 error, rather than saying 429 is reported.
Preserve the established third-person system-description style and the existing
explanation for unrecognized stream error codes.
---
Outside diff comments:
In `@concepts/events.mdx`:
- Around line 484-488: Update the introductory sentence in the recognized stream
error codes note to describe explicit event handling without stating that these
codes emit events instead of StreamError; preserve the existing 401, 409, and
429 mappings unchanged.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 5cc569f2-6a6e-4386-b97e-bff6ecc4f128
📒 Files selected for processing (3)
advanced/websocket-handling.mdxapi/client.mdxconcepts/events.mdx
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
All reported issues were addressed across 3 files
You’re at about 96% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
…t syntax, passive voice
Dismissed because a newer commit was pushed; Greptile will re-review the current head.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a0192a0f08
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Dismissed because a newer commit was pushed; Greptile will re-review the current head.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3ce604fab6
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| ### StreamError | ||
|
|
||
| **Emitted:** For unrecognized stream error codes (codes not matching 401, 409, 429, 503, 515, or 516) | ||
| **Emitted:** For a `429` (rate-limited) stream error, and for unrecognized stream error codes (codes not matching 401, 409, 503, 515, or 516). Since [#1263](https://github.com/oxidezap/whatsapp-rust/pull/1263), the client reports 429 the same way as every other coded branch — WhatsApp Web's own handler has no arm for it either (only `500..600` is special-cased there), so this is an embedder-facing choice rather than a fidelity fix. |
There was a problem hiding this comment.
The parenthetical now defines an unrecognized code as any code not matching 401, 409, 503, 515, or 516, which makes 429 satisfy that definition even though this sentence and the list below treat it as a specific rate-limit case. Retain 429 in the exclusion list while separately noting that it emits the generic StreamError event.
Useful? React with 👍 / 👎.
| - **401** → `LoggedOut` (session invalidated) | ||
| - **409** → `StreamReplaced` (another client connected) | ||
| - **429** → No event emitted (reconnects with extended backoff) | ||
| - **429** → `StreamError` (rate limited; also reconnects with extended backoff) |
There was a problem hiding this comment.
Once 429 reaches this event, the unchanged usage example above prints Unknown stream error for a known rate-limit condition. Consumers who copy the example will therefore misclassify 429s in their logs; use a neutral label or branch on err.code before describing the event as unknown.
Useful? React with 👍 / 👎.
|
|
||
| When the server returns a 429 stream error, the client bumps the internal backoff counter by 5 Fibonacci steps before reconnecting. This means the reconnection delay jumps significantly (e.g., from ~1s to ~13s on the first rate limit) to respect the server's throttling. | ||
|
|
||
| As of [#1263](https://github.com/oxidezap/whatsapp-rust/pull/1263), the client also dispatches an `Event::StreamError` (code `"429"`) — WhatsApp Web itself gives no signal for this case (its handler only special-cases `500..600`), but an embedder has no UI to fall back on, so a rate-limited session is now observable the same way every other coded stream error is. This is in addition to, not instead of, the `Event::Disconnected` the shared connection-loss path already dispatches once the socket actually closes — the 429 handler never marks the disconnect as expected, so it takes the same route every other unexpected drop does. |
There was a problem hiding this comment.
The added paragraph packs change history, WhatsApp Web behavior, embedder rationale, event ordering, and reconnect semantics into two long sentences. Split these into single-idea sentences so the event contract remains easy to scan and complies with the repository's explicit concise-sentence standard.
AGENTS.md reference: AGENTS.md:L25-L25
Useful? React with 👍 / 👎.
…n, neutral example label
Dismissed because a newer commit was pushed; Greptile will re-review the current head.
There was a problem hiding this comment.
All reported issues were addressed across 3 files (changes from recent commits).
You’re at about 97% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.
Tip: Review your code locally with the cubic CLI to iterate faster.
Re-trigger cubic
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Dismissed because a newer commit was pushed; Greptile will re-review the current head.
There was a problem hiding this comment.
0 issues found across 1 file (changes from recent commits).
Confidence score: 5/5
- Automated review surfaced no issues in the provided summaries.
- No files require special attention.
You’re at about 97% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.
Auto-approved: Docs-only PR updating three pages to reflect that a 429 stream error now emits StreamError; no code or behavior change here, and no public-contract or operational tradeoff requiring human judgment.
Re-trigger cubic
2 participants
Summary
whatsapp-rust #1263 changed
handle_stream_errorso that a429(rate-limited)<stream:error>now dispatchesEvent::StreamErrorin addition to the existing extended-backoff behavior — previously no event was emitted for 429, only the internal Fibonacci backoff counter was bumped. WhatsApp Web itself gives no UI signal for this case (its handler only special-cases the500..600range), but an embedder has no UI to fall back on, so 429 is now reported the same way every other coded stream error is.Three docs described the old (no-event) behavior for code 429 and are updated here to match:
advanced/websocket-handling.mdx— "Error code behavior" table:429row'sEventcolumn changed fromNoneto`StreamError`, plus a sentence added to the Fibonacci backoff section noting the new dispatch and linking PR #1263.api/client.mdx— "Stream error handling" table:429row'sEvent emittedcolumn changed fromNone (emits `Disconnected`)to`StreamError`, plus a new paragraph under "Rate limiting (429)" explaining the change.concepts/events.mdx—StreamErrorevent's "Emitted" description and the "recognized codes" bullet list updated: 429 no longer says "no event emitted"; it now documents thatStreamErrorfires for 429 same as unrecognized codes.No other content in these files was touched, and nothing under
changelog/was modified.Test plan
Generated by Claude Code
Summary by cubic
Docs now reflect that a 429
<stream:error>emitsEvent::StreamError(and thenEvent::Disconnected) while still using extended backoff (+5), matchingwhatsapp-rustPR #1263. Updatedadvanced/websocket-handling.mdx,api/client.mdx, andconcepts/events.mdxto make 429 observable, merge StreamError emission cases into one lead sentence, and tighten wording.Written for commit f835e7d. Summary will update on new commits.
Summary by CodeRabbit
Bug Fixes
StreamErrorevent in addition to triggering reconnect backoff.Documentation