Поиск проблем

401 Unauthorized на любой запрос

Симптом: на /api/v1/verifications/ приходит {"detail": "Invalid token."}.

Проверьте:

1. Заголовок: Authorization: Bearer tn_live_<prefix>_<secret> (с пробелом после Bearer, без кавычек вокруг токена).
2. Токен полный — все три части (tn_live_, prefix 8 символов, секрет). Часто при копировании из дашборда теряется хвост.
3. Ключ не отозван в дашборде → Keys.
4. Окружение токена соответствует окружению API (сейчас все ключи tn_live_* для прода app.truenum.ru).

400 {"phone": ["Invalid phone number"]}

Симптом: при POST /verifications/ валидация падает на phone.

Проверьте:

1. Формат E.164: +<country_code><number>, только цифры после +, без пробелов / дефисов / скобок.
2. Длина: от 8 до 15 цифр (плюс ведущий +).
3. Реальный код страны и валидная структура номера.

Примеры:

Неверно	Верно
8 999 123-45-67	+79991234567
+7 (999) 123-45-67	+79991234567
9991234567	+79991234567 (нет кода страны)
+0123	(слишком короткий)

Сообщение об ошибке нормализованное — мы не раскрываем, что именно не понравилось парсеру, чтобы атакующий не мог энумерировать формат.

400 {"webhook_url": [...]}

Возможные сообщения:

• "Enter a valid URL." — невалидный URL (пропущен scheme, плохой синтаксис).
• "URL host is not allowed (private/loopback/link-local)." — хост резолвится в приватный диапазон. Используйте публично доступный URL.
• "URL scheme must be http or https." — неподдерживаемая схема.
• "URL too long." — длина >500 символов.

Для локальной разработки используйте ngrok или cloudflared для проброса наружу.

429 Too Many Requests

Симптом: {"detail": "Request was throttled. Expected available in N seconds."} + заголовок Retry-After: N.

Что делать:

1. Дождитесь N секунд, повторите.
2. Внедрите client-side token bucket: 120 токенов, пополнение 2/сек.
3. Если упираетесь регулярно — пишите в саппорт за увеличением лимита.

См. Лимиты.

503 no_dial_number_available

Симптом: {"error": "no_dial_number_available", "retry_after": 60}.

Причина: все наши DID заняты другими активными верификациями. У каждого DID одновременно может быть только одна активная верификация до её завершения или истечения TTL.

Что делать:

1. Подождите retry_after секунд (обычно 60).
2. Повторите с экспоненциальным backoff: 60 → 120 → 240 секунд.
3. Максимум 3 попытки. После — сообщите пользователю «временные технические проблемы, попробуйте через 5 минут».
4. Если стабильно упираетесь — масштабирование DID-пула. Напишите в саппорт.

Webhook не приходит

Чек-лист:

1. Дашборд → Webhooks → Deliveries → ваша верификация:
2. HTTP-код от вашего эндпоинта.
3. Если 5xx / timeout / connection refused — проблема у вас.
4. Ваш приёмник доступен из интернета? Проверьте:

   curl -X POST https://your-app.example.com/webhook \
     -H 'Content-Type: application/json' \
     -d '{}'
   

5. Эндпоинт отвечает < 10 секунд? Если медленнее — мы считаем таймаут.
6. TLS-сертификат валидный? Self-signed не подходит.
7. Не блокирует ли firewall наши egress-IP? (Мы можем менять их без предупреждения — не белолистите по IP.)

См. Ретраи.

caller_id отличается от phone

Симптом: webhook пришёл с type: "verification.completed", но caller_id !== phone из исходного запроса.

Это нормально: значит, звонок был, но не с того номера, который пользователь ввёл при регистрации. Возможные причины:

• Пользователь намеренно позвонил с другого телефона.
• Перенаправление вызовов на другой номер.
• Маскировка caller-ID (редко).

Что делать: на вашей стороне отклонить верификацию. Не помечайте номер как подтверждённый. Покажите пользователю «номер не совпал».

Подпись webhook'а не проходит

См. Webhooks: подпись — раздел «Что делать при неудачной верификации».

Кратко: проверьте, что HMAC считается по <t>.<raw_body> (с точкой!), секрет актуальный, тело — сырые байты до парсинга JSON.

404 на GET /verifications/{id}/

Возможные причины:

1. Неверный verification_id (опечатка).
2. Верификация принадлежит другой компании (другому API-ключу). Эндпоинт возвращает 404 а не 403, чтобы не раскрывать факт существования чужих ресурсов.
3. Верификация была удалена согласно нашему retention policy (срок хранения данных верификаций — 90 дней).

Звонок не доходит / dial_number не отвечает

Это инцидент на нашей стороне. Проверьте:

1. dial_number из ответа набран полностью, включая + и код страны.
2. Звонок с другого телефона — может ваш оператор блокирует исходящие на этот номер.
3. Дашборд → Status (если есть) или Twitter/Telegram-канал статусов.

Если стабильно — напишите в саппорт с verification_id, временем звонка и номером, с которого звонили.

Где смотреть детали

Дашборд app.truenum.ru:

• Verifications — все ваши верификации, статусы, временные метки.
• Webhooks → Deliveries — каждая попытка доставки, HTTP-коды, тело запроса/ответа.
• Keys — список ключей, last_used_at, можно отзывать.

Поддержка: реквизиты в дашборде → Account.