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

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

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

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

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

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

Код	Когда
`201`	Проверка создана
`200`	Успешный запрос статуса, баланса, проверки кода
`400`	Некорректный запрос: формат номера, неверный код, неизвестный метод
`401`	Неверные `api_key` / `api_secret`
`402`	Проверку нельзя начать: нет средств, нет свободного канала, нет тарифа
`403`	Метод закрыт для вашего аккаунта
`404`	Сессия с таким `request_id` не найдена
`409`	Сессия уже завершена — подтверждена, истекла или отклонена
`422`	Канал не может доставить на этот номер
`502` / `503`	Отказ или недоступность поставщика на нашей стороне

Тело ошибки

Все ошибки приходят в формате Problem Details, одинаковым телом на любом эндпоинте:

{
  "type": "https://httpstatuses.io/400",
  "title": "Bad Request",
  "status": 400,
  "detail": "Unsupported verification method.",
  "instance": "POST /v1/verify",
  "error_code": "validation_error",
  "trace_id": "00-695d0ed5dddfb4f56c13602834697387-5ff95907ea42cb09-00"
}

Ветвитесь по error_code, а не по detail и не по status. detail — текст для человека, он меняется; один и тот же код ответа покрывает разные причины. trace_id приложите к обращению в поддержку — по нему мы находим запрос в логах.

Отдельных полей у ошибки может быть больше: на неверном коде приходит attempts_remaining — сколько попыток осталось до того, как сессия будет отклонена.

Коды ошибок

`error_code`	HTTP	Что произошло	Что делать
`validation_error`	400	Запрос не прошёл проверку: формат номера, отсутствующее поле, неизвестный метод	Исправить запрос; метод с опечаткой или неподключённый на платформе попадает сюда же
`region_not_supported`	400	Номер не российский	Сейчас поддерживаются только `+7`
`invalid_code`	400	Пользователь ввёл неверный код	Показать «Неверный код», учесть `attempts_remaining`
`invalid_credentials`	401	Неверные `api_key` / `api_secret`	Проверить учётные данные
`insufficient_balance`	402	На балансе не хватает средств на это подтверждение	Пополнить баланс
`no_gateway_available`	402	Нет свободного канала доставки прямо сейчас	Повторить через несколько секунд или переключиться на другой метод
`pricing_unavailable`	402	Для метода нет действующего тарифа	Обратиться в поддержку — это не ваша ошибка
`method_not_available`	403	Метод закрыт для вашего аккаунта	Запросить подключение
`not_found`	404	Сессии с таким `request_id` нет	Проверить идентификатор
`not_pending`	409	Сессия уже завершена: подтверждена, истекла или отклонена	Создать новую проверку
`delivery_unavailable`	422	Канал не может доставить на этот номер	Переключиться на другой метод — каскадом
`provider_error`	502	Поставщик отказал	Повторить или переключить метод
`lookup_unavailable`	503	Сервис проверки номера недоступен	Повторить позже

Коды стабильны: мы можем добавить новый, но не переименовываем существующие. Неизвестный код обрабатывайте как общую ошибку своего класса status, а не падайте на нём.

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

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

Тело ошибки​

Коды ошибок​

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

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

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

Тело ошибки

Коды ошибок

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