Если код приходит на российский номер, но не доходит на зарубежный, не отправляйте его десять раз подряд. Создайте одну тестовую попытку, сохраните внутренний `verification_id`, ответ SMS-провайдера и идентификатор попытки. Сначала подтвердите номер в международном формате E.164, затем проверьте разрешение страны и финальный статус доставки. Так видно, запрос не был принят вообще или был принят, но остановился дальше по маршруту.
Сообщение «код отправлен» в интерфейсе должно означать только то, что приложение зарегистрировало попытку. HTTP 200 или статус `pending` у Verify ещё не доказывает появление SMS на телефоне. Пользователю лучше показать нейтральное сообщение и доступный резервный канал, а подробную причину оставить в защищённом журнале без самого OTP.
Одна попытка становится трассировкой, а не догадкой
Для разбора нужны одинаковые поля на всех этапах: ваш request ID, хеш или маска номера, страна, канал, provider attempt ID, время в UTC, ответ API и последующие события. Полный номер и код подтверждения в обычный application log не попадают. Связь между событиями строится по внутреннему ID и идентификатору провайдера.
verification_id=ver_01J...
destination=+49******731
country=DE
channel=sms
provider_attempt=VLxxxxxxxxxxxxxxxx
accepted_at=2026-10-07T10:20:31Z
provider_status=pending
provider_error=null| Наблюдение | Что уже известно | Следующий шаг |
|---|---|---|
| API вернул 4xx | сообщение не поставлено в маршрут | прочитать точный error code и request parameters |
| attempt создан, status pending | провайдер принял задачу | получить status/error следующего события |
| blocked по географии | страна запрещена настройкой аккаунта | сверить Geo Permissions и требования страны |
| undelivered/failed у оператора | запрос дошёл дальше API | разобрать provider/carrier code и sender route |
| delivered, SMS нет в inbox | оператор подтвердил доставку, но не чтение | проверить устройство, фильтр спама и правильность номера |
Номер нормализуется до обращения к провайдеру
Twilio Verify требует телефон в формате E.164. Это плюс, код страны и национальная часть без пробелов и локального префикса набора. Нельзя просто удалить из ввода все нецифровые символы: ведущий ноль в национальном формате и код страны имеют разный смысл. Парсеру передают исходную строку и выбранную страну, а результат проверяют библиотекой телефонных номеров.
input: 030 1234567
region: DE
E.164: +49301234567
stored: raw_input + region + e164
log: +49******567- Не подставлять страну по IP как окончательное решение: VPN и поездка меняют геолокацию, но не номер.
- Не хранить разные написания одного номера как разные аккаунты; ключом сравнения служит нормализованное значение.
- Показывать пользователю распознанную страну и маскированный номер перед отправкой.
- Отдельно обрабатывать номера, которые не соответствуют плану нумерации, до платного API-вызова.
Географическое разрешение не равно доступному маршруту
В Twilio Verify Geo Permissions управляют трафиком по странам. Отключённая страна блокирует отправку, а safe list может использоваться для ограниченного теста. У обычного Messaging ошибка 21408 указывает, что регион выключен или канал туда не поддерживается. Разрешать все страны ради одного инцидента опасно: форма OTP становится целью SMS pumping, и злоумышленник генерирует дорогой трафик.
После включения нужной страны всё равно проверяют требования назначения: тип sender, предварительную регистрацию бренда или шаблона, допустимый текст и поддержку конкретного канала. Настройка аккаунта не отменяет правила оператора и страны. Если маршрут не поддерживается, ошибка должна переводить пользователя на действительно доступный канал, а не запускать бесконечный retry.
Повторная отправка имеет состояние и лимит
Кнопка «Отправить ещё раз» не создаёт параллельные коды без контроля. Сервер хранит активную verification session, время последней попытки, число отправок и проверок, а также выбранный канал. Клиентский таймер нужен для интерфейса, но решение принимает сервер. Лимит задают как по аккаунту/номеру, так и по IP или устройству, чтобы не блокировать весь офис за действия одного пользователя.
- Если активная попытка ещё обрабатывается, вернуть её состояние без новой SMS.
- После разумной паузы разрешить resend в пределах серверного лимита.
- При явном permanent failure предложить другой разрешённый канал.
- После нескольких ошибок замедлить поток и потребовать дополнительный антифрод-сигнал.
- Не сообщать, зарегистрирован ли номер: одинаковый ответ снижает риск перебора аккаунтов.
Тестовая матрица отделяет страну от конкретного телефона
Возьмите по одному разрешённому тестовому номеру для каждой реально поддерживаемой страны и проверяйте их после изменения маршрута или sender. Для каждого запуска фиксируйте E.164, страну, тип номера, канал, provider attempt ID, принятие API, delivery status и фактическое получение. Один личный номер разработчика не представляет всех операторов страны.
| Сценарий | Ожидаемый результат | Что доказывает |
|---|---|---|
| разрешённая страна, корректный мобильный номер | attempt принят и код получен | базовый маршрут работает |
| страна выключена | предсказуемый blocked/error без SMS | geo policy применяется |
| невалидная национальная строка | ошибка до API | нормализация защищает бюджет |
| быстрые повторные нажатия | одна активная сессия и rate limit | нет SMS-лавины |
| SMS недоступна, fallback разрешён | переход на voice/WhatsApp/email по политике | резервный путь реальный |
Что приложить к заявке провайдеру
Если формат, страна и настройки верны, а попытки стабильно завершаются ошибкой у одного оператора, подготовьте время UTC, страну и маску номера, provider attempt ID, channel, sender, status и error code. Не прикладывайте OTP, auth token и полный номер в публичный тикет. После ответа повторите один контролируемый тест и сохраните результат рядом с изменением конфигурации.
Готовое исправление подтверждается не зелёным ответом API, а воспроизводимой доставкой на тестовых маршрутах, ограниченным resend и понятным fallback. Для повторного разбора достаточно обезличенного журнала одной попытки и списка стран, которые продукт действительно поддерживает.