When phone auth fails for a configuration reason, don't let signup treat it as a bad number

The problem: a platform error that looks like a user error

In the public question, the failure comes from app signing configuration, not from the phone number. A user who typed a perfectly good number still cannot finish. The risk for your application is a handler that maps every non-success into "invalid phone" and rejects the signup, or one that retries forever. Neither is right. A configuration error says nothing about the number, ownership or reachability. Your decision is how to route results that are neither a clean pass nor a proven invalid number. The fixture gives you named branches to practise that decision locally, with Python 3.10+, no credentials and no network calls.

What the fixture actually implements

Implemented behavior: the phone function takes a branch (normal, unknown, provider_failure, otp) and returns mode, branch, otp_sent, live_line_type_available, state, valid, line_type and next. It sends nothing, calls no provider and verifies no signature. Every branch returns mode synthetic_fixture, otp_sent false and live_line_type_available false. Any other branch raises UNSUPPORTED_FIXTURE. Expected outputs: normal returns state simulated, valid true, line_type mobile, next continue_customer_policy. unknown returns state unknown, valid null, line_type null, next review_or_existing_otp. provider_failure returns state unknown, valid null, line_type null, next bounded_retry_then_review. otp returns state unsupported, valid null, line_type null, next customer_otp_provider. The mobile value is synthetic; the current free production route does not request line type, ownership, reachability or OTP delivery.

Worked hypothetical: mapping a signing failure

Hypothetical scenario: a small team's Android signup calls its existing OTP provider, and the provider rejects the request with an app-fingerprint error similar to the public question. Proposed application design, not fixture behavior: your adapter classifies that response as a provider failure, which you rehearse with the provider_failure branch. The expected fixture output is state unknown, valid null, next bounded_retry_then_review. Your code then retries a small fixed number of times, records the error class for engineers, and moves the signup to review instead of rejecting it. Because valid is null, not false, the user is never told their number is wrong. A configuration error usually will not clear on retry, so the bound matters: the team should fix signing configuration while the signup waits in review.

Failure handling your code owns

The fixture names next steps; your application must implement them. Proposed rules: treat valid null as no conclusion, never as rejection. Cap retries for provider_failure and alert on repeated configuration errors. For unknown, offer review or the OTP you already run. For otp, next customer_otp_provider means your own provider must send the code; the fixture reports otp_sent false and never sends a message. Reject unexpected branches loudly, as the fixture does with UNSUPPORTED_FIXTURE. Keep this phone flow separate from the identity fixture's local permission records and synthetic callbacks; they are fixture data, not live business permission, and its recover step expires sessions locally without polling any provider.

Acceptance checklist

Before a sandbox request, confirm: all four branches run and match the outputs above; your handler never rejects when valid is null; provider_failure retries are bounded and end in review; configuration errors are logged separately from user input errors; otp_sent false is never shown as a sent code; live_line_type_available false stops any logic depending on line type; an unsupported branch fails visibly. Then run the engineering tests with the unittest command in the guide. They cover simulated transitions, not production success. Live route availability needs separate confirmation; eligible businesses can enroll for free Basic Lookup with a 60 requests per minute technical limit, which still returns no line type or ownership.

Run the checked synthetic example

Download and extract https://gridzen.ai/downloads/verification-delivery.zip, enter verification_delivery, then run with Python 3.10+. This local example makes no network calls. Use a fresh database for an independent identity run.

python3 delivery.py phone --branch unknown
python3 delivery.py phone --branch provider_failure

Sources and scope

https://gridzen.ai/guides/signup-phone-check/ https://gridzen.ai/guides/current-capabilities/ Based on the checked source snapshot and local fixture; proposed application rules are design advice, not proven production behavior. Written with AI assistance and reviewed independently.