Stop cleanly when Apple takes a code and then fails anyway

[parawanderer]

Fixes #168.

What happened

td_2fa_submit does two things: it submits the verification code, and then runs a full Grand Slam re-authentication behind it. The reported log shows the first half succeeding and the second answering 503:

00:15:04,441  Detected 2FA requirement: trustedDeviceSecondaryAuth  →  REQUIRE_2FA
00:15:17,155  Attempting authentication for user …     ← the re-auth inside td_2fa_submit
00:15:17,663  UnhandledProtocolError: Error response for GSA request: 503

Attempting authentication for user is logged only by _gsa_authenticate (account.py:1412) and appears twice, which is what places the failure. The submit to _ENDPOINT_2FA_TD_SUBMIT never raised — the code was accepted.

Reproduced independently since. It is weather.

(The two different email spellings in that log are the same logger.info firing twice — the reporter's own inconsistent redaction, not a bug. Noted so nobody chases it.)

The actual defect is the message, not the retrying

_submit_code_with_retries caught only InvalidCredentialsError, so this escaped the loop, escaped log_in, and landed in the wizard's catch-all handler:

{type}: {message} … If this looks like a bug, please report it with that file: <issue link>

The tool asked for this issue. #168 exists because we told a user to open it about Apple having a bad minute.

Nothing is retried, and that is the finding

Three recoveries existed. Only one is known to work:

Re-type the code	Cannot work — the half that succeeded spent it
Send a new code and carry on	Untested. Nobody has observed this recovering
Start the sign-in again shortly	What actually worked, both times

The second is the one worth being explicit about refusing. The sign-in after the reproduced 503 was refused at the password step — which looks like Apple throttling the account or the machine identity for a window, not one endpoint hiccupping. Sending two more codes into that is how a throttle becomes a lock, and it can only ever be tested on somebody's real account. Rule 15's point: the wrong remedy costs more than none.

So it stops, and says so.

Why ExportSourceError

Both front ends already show one as a plain message with no bug link — so the fix needs no new handler in either. from e keeps 503 in the message and in __cause__, so the status still reaches a log with a traceback under it.

The message also warns that the next password attempt may be refused once, because that happened and would otherwise read as a second, unrelated fault.

Tests

Seven, and all verified failable:

Break	Turns red
let the protocol error escape unchanged (the original bug)	4
retry instead of stopping	4

One of those asserts retry_code is never consulted — that is what stops a later edit quietly offering the untested recovery, since a retry path that never runs looks harmless in review.

567 passed, 2 skipped across python/test and opentagviewer_export. flake8 and pyright clean.

Not fixed here

• The Android app has the same bug. Same library, same 503, and UnhandledProtocolError reaches ErrorReportActivity — the "this one is a bug" page. Needs its own change.
• FindMy.py folds every non-OK status into UnhandledProtocolError, carrying only the number, so nothing downstream can tell a 503 from a genuinely unmodelled response without parsing the message. Fixing that upstream would let both consumers classify properly instead of casting the wide net this PR casts.

---

🤖 Generated with Claude Code