Phone Verification Debugging for Game Recovery — Correlating Send and Verify Evidence

Short answer: treat a phone verification attempt as one trace that spans send, delivery, and verify, then make every transition auditable before you tune a provider or retry policy. I build tools for developers, so my first question is usually boring: can I explain one failed attempt from a single request ID? If the answer is no, the system is not ready for an audit. A player saying “the code never arrived” is not a useful diagnostic fact. It could mean the send request was rejected, the message was delayed, the client displayed an old code, or the verify endpoint received a different phone number. This is a gaming recovery flow, where an account may be worth years of purchases and saved progress. The recovery path has to be forgiving to a tired player and strict enough to resist account takeover. Those goals pull in opposite directions. What should a trace contain across phone verification send and verify steps? Start with a state machine, not a pair of unrelated endpoints. Create an attempt record before sending anything. Give it a random, non-sequential attemptId , a normalized phone hash, an expiry time, and a server-side status. Never log the code itself or the full phone number. The minimum useful states are created , send_accepted , send_rejected , verified , expired , and locked . A delivery receipt can add delivered or undeliverable , but delivery is evidence about a message, not proof that a player typed the right code. Keep those concepts separate. Here is the smallest shape I would put behind both handlers: type VerificationStatus = | " created " | " send_accepted " | " send_rejected " | " verified " | " expired " | " locked " ; type VerificationAttempt = { attemptId : string ; accountId : string ; phoneHash : string ; status : VerificationStatus ; createdAt : string ; expiresAt : string ; sendRequestId ?: string ; verifyRequestId ?: string ; failureCode ?: string ; }; I also store a transition event with a timestamp, actor ( server , carrier_receipt , o