fix(weixin): distinguish ret=-2 'prepare failed' from genuine rate limit (#80125)

[JonthanaHanh]

Summary

iLink returns ret=-2 for both rate limits AND parameter errors. When errmsg is "prepare failed", the real cause is a missing/invalid context_token (e.g. fresh account with no inbound messages yet), not frequency limiting.

Previously this was unconditionally treated as a rate limit, opening a 30s circuit breaker and hiding the real cause behind "iLink sendmessage rate limited; cooldown active for 30.0s".

Changes

In _send_text_chunk_locked (gateway/platforms/weixin.py), added a check before the generic rate-limit handler:

• ret=-2 + errmsg="prepare failed" raises a descriptive RuntimeError immediately: "iLink sendmessage parameter error: prepare failed (likely missing context_token -- user must send an inbound message first or re-pair)"
• Does NOT trigger the rate-limit circuit breaker
• Genuine rate limits (ret=-2 with other errmsg values) continue to work as before

Impact

1. Diagnostics: operators see the real cause instead of a misleading "rate limited" message
2. Recovery: the error message guides users to send an inbound message or re-pair
3. No regression: stale session handling (errmsg="unknown error") and genuine rate limits are unchanged

Fixes #80125

[alt-glitch]

This was generated by AI during triage.

Duplicate of #80152, the earlier open fix for #80125. Both distinguish iLink ret=-2 with prepare failed from a genuine rate limit so the context-token error is surfaced without opening the cooldown breaker.

[x7peeps]

Hi @JonthanaHanh — heads-up that this PR overlaps with #80152 (also open, fixing #80125 with the same approach: treat iLink ret=-2 + "prepare failed" as a missing/invalid context_token parameter error rather than a rate limit).

#80152 is the more complete implementation (unit helper + 8 regression tests covering breaker-not-opened and fail-fast behavior, plus a token_dir hint in the error message), and it's been rebased on latest main. To land the fix once, I'll close this PR in favor of #80152 — happy to reconsider if you'd prefer to merge the changes here instead. Thanks for surfacing the same bug!

[x7peeps]

Following up on the overlap note (no reply from the author yet). To keep the fix landing cleanly, this PR should be closed in favor of #80152 — it fixes the same bug (#80125) but with full coverage:

• fix(weixin): 区分 ret=-2 的 'prepare failed' 参数错误，不再误报为限流 #80152 (this stays): _is_context_token_error_ret() helper + 7 unit tests + integration test asserting the circuit breaker is NOT opened, fail-fast (no retry/backoff), and a subsequent healthy send succeeds. Error message includes the token_dir hint. Rebased on latest main.
• fix(weixin): distinguish ret=-2 'prepare failed' from genuine rate limit (#80125) #80156 (this): inline check, no tests, stale baseline.

@JonthanaHanh @NousResearch/maintainers — recommend closing this as duplicate of #80152 so the fix lands once. Happy to rebase/merge either direction if the author prefers to keep theirs.

[x7peeps]

Hi @JonthanaHanh — this PR and #80152 fix the same root cause (#80125: weixin ret=-2 + "prepare failed" being misreported as rate limit).

Comparing the two objectively:

	#80152	#80156
Files	gateway/platforms/weixin.py + tests/gateway/test_weixin.py	gateway/platforms/weixin.py only
Test coverage	Regression tests (asserts prepare failed is NOT treated as rate-limit; real ret=-2 rate-limit still cooldowns)	None
Structure	Extracts _is_context_token_error_ret() helper + CONTEXT_TOKEN_ERROR_ERRMSG constant	Inline check in _send_text_chunk_locked
Base freshness	Based on current main	—

#80152 is the more complete fix (regression tests + helper abstraction) and already has CI running. Since I can't close a PR I don't own, I'd suggest we keep #80152 and close this one as duplicate — or if you prefer to keep this, let me know and I'll close mine. Either way, thanks for independently catching the same issue!

[kshitijk4poor]

Landed on main via #115359 (merge 5db9f02372) with a Co-authored-by for you on the salvaged commit bd39167c56 — #80152 by @x7peeps was opened five minutes earlier with the same change, so it carries the author line. Thank you — closing as merged through the salvage.