invalid_code

Docs version v1 (main) · Nauthera is pre-1.0, in a design-partner program

The second-factor or recovery code was wrong or already used (401).

#Meaning

A TOTP code, an emailed one-time code or a recovery code did not verify at a hosted UI MFA endpoint (/v1/auth/mfa/*): it was wrong, outside the acceptance window, or a code already used once. The answer is the same for each, so it does not reveal which.

#Impact

The user stays on the second-factor step. An occasional one is expected: a mistyped code or one that expired while being typed. Repeated failures lock that method after mfa.max_failures (5) for mfa.lock_duration (15m), and further attempts answer too_many_requests.

#Diagnosis

1. Look the request id up on the Troubleshooting page. The attempt is recorded on the verification action (for example mfa.totp.verified) with reason invalid_code and a cause such as code_mismatch, code_replayed, code_malformed or clock_skew.
2. Many clock_skew causes for one user point at the phone's clock; for everyone, at the server's.

#Mitigation

• As a user: wait for the next code in the authenticator app and enter it once; check the phone's time is set automatically. If the device is gone, use a recovery code.
• As an operator: keep server clocks synchronised. mfa.drift (0, 1 or 2 steps) widens the window, at a cost in security.

#Escalation

Escalate when correct codes fail for many users at once. Check NTP on the replicas first. Open an issue with request ids, the audit causes and the server version. Never attach codes, recovery codes or TOTP seeds.

Problem code runbooks · Generated from internal/runbook/problems.yaml in nauthera-server.