docs: 429 stream error now dispatches StreamError event

advanced/websocket-handling.mdx

@@ -1047,7 +1047,7 @@ Each stream error sets `is_logged_in = false` and fires the `shutdown_notifier`
 |------|--------|-------|-------------|
 | **401** | Disables auto-reconnect | `LoggedOut` | No — session invalid, must re-pair |
 | **409** | Disables auto-reconnect | `StreamReplaced` | No — prevents displacement loop |
-| **429** | Adds 5 to backoff counter | None | Yes — extended Fibonacci backoff |
+| **429** | Adds 5 to backoff counter | `StreamError` | Yes — extended Fibonacci backoff |
 | **503** | Normal handling | None | Yes — standard backoff |
 | **515** | Marks as expected disconnect | None | Yes — immediate, no backoff |
 | **516** | Disables auto-reconnect | `LoggedOut` | No — device removed |
@@ -1119,7 +1119,7 @@ Maximum:  900s (15 minutes)
 Jitter:   ±10%
 ```
 
-For rate-limited errors (429), the backoff counter is incremented by 5 before the normal increment, causing the delay to jump significantly on the next reconnection attempt.
+For rate-limited errors (429), the client increments the backoff counter by 5 before the normal increment, causing the delay to jump significantly on the next reconnection attempt. Since [#1263](https://github.com/oxidezap/whatsapp-rust/pull/1263), the client also dispatches `Event::StreamError` for 429 — WA Web gives its UI no signal here at all (429 is outside the `500..600` range its handler special-cases), but an embedder has no UI to fall back on, so the rate limit is reported like every other coded stream error.
 
 **Stability-gated reset.** The backoff counter does not reset to its base immediately on a successful `<success>` authentication. Instead, `connected_at_ms` records the auth time, and the counter only resets when the *next* disconnect finds the connection was stable for at least `STABLE_CONNECTION_RESET_MS` (30s) — matching WA Web's `resetDelay`. A connection that authenticates and then immediately drops keeps escalating the backoff instead of resetting to 1s and retrying in a tight loop.
 

api/client.mdx

@@ -495,7 +495,7 @@ The client handles specific `<stream:error>` codes from the WhatsApp server:
 |-------------------|---------|---------------|----------------|
 | **401** | Session invalidated (unauthorized) | `LoggedOut` | Disabled — must re-pair |
 | **409** | Another client connected (conflict) | `StreamReplaced` | Disabled — prevents displacement loop |
-| **429** | Rate limited (too many connections) | None (emits `Disconnected`) | Yes, with extended backoff (+5 steps) |
+| **429** | Rate limited (too many connections) | `StreamError`, then `Disconnected` | Yes, with extended backoff (+5 steps) |
 | **503** | Service unavailable | None | Yes, normal backoff |
 | **515** | Expected disconnect (e.g., post-pairing) | None | Yes, immediate (no backoff) |
 | **516** | Device removed | `LoggedOut` | Disabled — must re-pair |
@@ -509,6 +509,8 @@ When you receive a `LoggedOut` or `StreamReplaced` event, auto-reconnect is perm
 
 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.
+
 ### General reconnection behavior
 
 | Scenario | Behavior |

concepts/events.mdx

@@ -463,7 +463,7 @@ Event::LoggedOut(logout) => {
 
 ### 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.
 
 ```rust
 #[derive(Debug, Clone, Serialize, bon::Builder)]
@@ -482,10 +482,10 @@ Event::StreamError(err) => {
 ```
 
 <Note>
-Recognized stream error codes emit specific events instead of `StreamError`:
+Specific stream error codes have the following event behavior:
 - **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)
 - **503** → No event emitted (reconnects with normal backoff)
 - **515** → No event emitted (immediate reconnect, e.g., after pairing)
 - **516** → `LoggedOut` (device removed)