docs(pair-code): document PairingCodeError, PairCodeRejection, and on_pair_code_error - #468
Conversation
…_pair_code_error Reflects whatsapp-rust#1191: pair_with_code now dispatches Event::PairingCodeError on failure (except CodeAlreadyOutstanding and Cancelled) so BotBuilder::with_pair_code's detached task has a way to report a refused request. Documents the new PairCodeRejection enum, PairError::rejection()/backoff()/lost_the_flow_to_another_request(), BotBuilder::on_pair_code_error, and the RequestFailed Display change. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FuiPJ7vgkeWaU7FdZJhoec
📝 WalkthroughWalkthroughPair-code documentation now covers structured failure events, rejection and backoff helpers, client event dispatch behavior, and detached bot pairing error handlers. ChangesPairing failure events
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related issues
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 |
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 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 `@api/bot.mdx`:
- Line 705: Update the documentation for on_pair_code_error to remove the claim
that it is the only way to observe with_pair_code failures, and state that
on_event also receives Event::PairingCodeError while retaining its role as the
dedicated convenience handler.
- Around line 723-730: Bound the retry loop in the throttled error handler
around client.pair_with_code so repeated PairingCodeError failures cannot
continue indefinitely. Track and enforce a maximum attempt count, or delegate
retries to the application’s retry policy, while preserving the server-provided
backoff delay for permitted retries.
In `@concepts/events.mdx`:
- Line 582: Rewrite the pairing-failure documentation in concepts/events.mdx
lines 582-582, concepts/authentication.mdx lines 525-527 and 1152-1156,
api/client.mdx line 281, and api/bot.mdx line 649 using concise, active,
second-person sentences. Separate event dispatch, returned errors, failure
classification, retry readiness, canonicalization, backoff, display behavior,
detached execution, and handler registration into distinct reader-focused
statements, preserving the documented behavior at each site.
- Around line 608-613: Update the PairingCodeError pattern in the event-handling
example to match rejection, backoff, and error while appending .. so it remains
valid for the non-exhaustive payload. Preserve the existing logging and
throttling logic.
🪄 Autofix (Beta)
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: 2038260a-5a22-4882-8ac1-4e3304705e48
📒 Files selected for processing (4)
api/bot.mdxapi/client.mdxconcepts/authentication.mdxconcepts/events.mdx
![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: 5d9dd02f0e
ℹ️ 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".
- Add `..` to the non-exhaustive PairingCodeError destructuring example (would not compile in a consumer crate) — flagged by CodeRabbit and Codex. - Bound the throttled-retry example in on_pair_code_error to a fixed attempt count instead of retrying forever, including for BadRequest (which may be permanently invalid input, not just throttling). - Clarify that on_pair_code_error is a convenience over on_event, not the only way to observe the event itself. - Correct the rejection: None description — it also covers a server response whose code/text pair doesn't classify, not just "no answer". Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FuiPJ7vgkeWaU7FdZJhoec
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4b2ae1b2da
ℹ️ 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".
An unrecognized server code doesn't yield rejection: None — from_server falls through to Some(PairCodeRejection::Unknown(code)) since Unknown's text() is None, so the mismatch guard never fires. None only happens for a *named* code paired with a contradicting text, or when the request never reached the server at all. My prior fix for a related CodeRabbit comment had this backwards. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FuiPJ7vgkeWaU7FdZJhoec
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
2 participants
Summary
Documents whatsapp-rust#1191, "feat(pair-code): report a refused pair-code request to the consumer."
Client::pair_with_codepreviously only returned its failure as anErr; when driven byBotBuilder::with_pair_code(a detached task), thatErrreached nobody, leaving a consumer waiting on a code with no way to learn none was coming. The PR adds a new event, a typed rejection status, and a bot-level handler to close that gap.Changes
concepts/authentication.mdxEvent::PairingCodeError(fields, when it fires, and the two exclusions —CodeAlreadyOutstandingandCancelled— where a code may still be on the way) and the newPairCodeRejectionenum (five named variants pinned to WA Web's own accepted set, theUnknown(i32)fallback,is_throttled(), andfrom_server's code/text pairing rule).PairError::RequestFailed'sDisplaynow renders exactly what it wraps instead of the fixed string"pair-code IQ request failed"; replaced the ad-hoc 400-vs-429 note withPairCodeRejection::is_throttled().api/bot.mdx— newon_pair_code_errormethod section (mirrors the existingon_pair_code_refresh), plus a note onwith_pair_codepointing at it as the only way to observe a detached-task failure.api/client.mdx—pair_with_code's error table and examples updated for theDisplaychange; documented the newPairError::rejection()/backoff()/lost_the_flow_to_another_request()methods and the event dispatch that now happens alongside the returnedErr.concepts/events.mdx— addedPairingCodeErrorto theEventenum listing and gave it a full entry in "Pairing Events," consistent with howPairingCode/PairingCodeRefreshare documented there.No changelog entry — per project convention, that file is human-authored only.
Generated by Claude Code
Summary by cubic
Documents pair-code failure reporting: a
PairingCodeErrorevent, thePairCodeRejectionenum, and theon_pair_code_errorhandler. Clarifies howClient::pair_with_codereports failures and updatesRequestFaileddisplay text, perwhatsapp-rust#1191.New Features
concepts/authentication.mdx: New “Pair code failure events” coveringEvent::PairingCodeError(fields, when it fires), exclusions (CodeAlreadyOutstanding,Cancelled), andPairCodeRejectionvariants withis_throttled(). Clarifiesrejection: Noneonly when the request never reached the server (validation/no connection/timeout) or when a named code is paired with a contradictingtext; unrecognized codes returnSome(Unknown(code)).api/bot.mdx: Addedon_pair_code_errordocs and notedwith_pair_coderuns detached; the event is how that path reports failures. States this handler is a convenience overon_event.api/client.mdx:pair_with_codenow dispatchesPairingCodeErroron failure; documentedPairError::rejection(),backoff(), andlost_the_flow_to_another_request(). ClarifiedRequestFailedDisplayrenders the wrapped server error (e.g.,429 (rate-overlimit)).concepts/events.mdx: ListedPairingCodeErrorwith a concise example.Bug Fixes
BadRequest) inon_pair_code_error; added..to the non-exhaustive destructuring example.rejection: Nonedocs to exclude unrecognized server codes (these map toUnknown(code)), and to include the named-code/contradicting-text case.Written for commit 1608199. Summary will update on new commits.