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

To effectively debug phone verification attempts in a game recovery system, it is crucial to treat the entire process as a single, auditable trace that spans from the send request to the verification step. Developers should be able to explain the outcome of a failed attempt based on a single request ID, rather than vague statements like "the code never arrived."

The trace should contain a state machine that captures the entire journey of a verification attempt, rather than treating the send and verify endpoints as unrelated entities. The minimum set of states to include are created, send_accepted, send_rejected, verified, expired, and locked. Each state should have a unique attemptId, a normalized phone hash, an expiry time, and a server-side status.

Logging should never include the actual code or the full phone number, as this information is sensitive. Instead, keep track of the minimum necessary information to understand the flow. A verification attempt can be represented by a type that includes the attemptId, accountId, phoneHash, status, createdAt, expiresAt, sendRequestId, verifyRequestId, failureCode, and any relevant transition events.

When storing the attempt, include a transition event with a timestamp, actor (server, carrier_receipt, or player), and a redacted reason for the change in status. This event stream will be invaluable for auditors to inspect later.

The request envelope should contain an attemptId, requestId, phase (send, delivery, or verify), outcome (accepted, rejected, delivered, or failed), code (optional), and occurredAt. The requestId must be generated at the edge and passed through all queues, provider adapters, and storage systems. If a retry creates a new provider request, maintain the same attemptId but record a new requestId.

To isolate failures during the send, delivery, and verify phases, use the phase boundaries as an investigation checklist. Do not infer a send failure from a missing verification; instead, ask what the last recorded transition was. Analyze the last known event to determine the outcome and take appropriate action.

By following this process, developers can build a robust, auditable system that effectively handles phone verification attempts in a gaming recovery flow. This approach ensures that players are treated with respect and privacy, while also providing valuable insights for debugging and improving the system.