Статусы и обработка ошибок

Статусы проверки

У каждой сессии есть статус. Он меняется по ходу проверки:

Статус	Что значит	Что делать
sent	Проверка инициирована, ждём действия пользователя	Опрашивать статус
delivered	Код/звонок доставлены пользователю	Опрашивать статус
verified	Номер подтверждён	Пропустить пользователя дальше
expired	Истёк срок сессии (expires_at)	Предложить начать заново
failed	Подтвердить не удалось	Предложить другой метод или повтор

verified, expired и failed — финальные статусы: после них опрашивать сессию больше не нужно.

Коды ответов HTTP

Код	Когда	Реакция
201	Проверка успешно создана	Показать номер/попросить код
200	Успешный запрос статуса, баланса, проверки кода	—
400	Некорректный запрос: неверный код, формат номера, истёкшая сессия	Показать пользователю понятную ошибку
401	Неверные api_key / api_secret	Проверить учётные данные
402	Недостаточно средств на балансе	Пополнить баланс
404	Сессия с таким request_id не найдена	Проверить идентификатор

Тело ошибки приходит в формате Problem Details:

{
  "type": "https://verificahub.ru/errors/insufficient-funds",
  "title": "Insufficient funds",
  "status": 402,
  "detail": "Недостаточно средств для инициирования проверки."
}

Рекомендации

• Тайм-аут. Если сессия дошла до expired, не пытайтесь её «дожать» — создайте новую.
• Идемпотентность на вашей стороне. Храните request_id и не создавайте новую проверку, пока активна текущая.
• Понятные сообщения. На 400 при вводе кода покажите «Неверный код» и дайте запросить новый.
• Мониторинг баланса. Ловите 402 и заранее предупреждайте о низком балансе — см. Баланс и статистика.