Ошибки и лимиты
Формат ошибки
{"error": "insufficient_balance", "message": "Недостаточно средств на балансе. Пополните его в кабинете."}
Ориентируйтесь на машинный код error. Поле message — текст на русском, он может меняться.
| HTTP | error |
Когда | Что делать |
|---|---|---|---|
| 400 | invalid_json |
Тело не JSON или больше 4 КБ | Исправить запрос |
| 401 | missing_api_key |
Нет заголовка Authorization |
Передать ключ |
| 401 | unauthorized |
Ключ не найден или отозван | Выпустить новый ключ |
| 402 | insufficient_balance |
На балансе меньше цены SMS | Пополнить баланс |
| 402 | daily_limit |
Исчерпан дневной лимит расхода | Поднять лимит или дождаться полуночи по Алматы |
| 403 | phone_blocked |
Номер в вашем чёрном списке | Не повторять |
| 403 | fraud_blocked |
Отказ антифрода, причина в поле reason |
Не повторять сразу |
| 403 | session_required |
Маршрут доступен только из кабинета | Выполнить действие в кабинете |
| 404 | not_found |
Объекта нет в вашем аккаунте | Проверить id |
| 422 | invalid_phone |
Не мобильный номер Казахстана | Исправить номер |
| 422 | invalid_purpose, invalid_ip, invalid_signals, invalid_options, invalid_metadata |
Неверное поле запроса кода | Исправить поле |
| 422 | invalid_before |
before в выписке не в формате RFC 3339 |
Исправить параметр |
| 429 | rate_limited |
Превышен лимит сессий на номер | Попросить пользователя подождать |
| 500 | internal |
Внутренняя ошибка | Повторить запрос позже |
Повторять автоматически имеет смысл только 500 и сетевые ошибки. Учитывайте, что POST /v1/verify не идемпотентен: если первый запрос на самом деле прошёл, повтор создаст вторую сессию.
Лимиты и антифрод
Лимит сессий на номер по умолчанию — 4 за 72 часа. Он не действует на тестовые номера, номера из белого списка и запросы с signals.is_trusted_user: true.
Правила антифрода настраиваются в разделе Антифрод. Значение 0 выключает правило.
reason |
Правило | По умолчанию |
|---|---|---|
ip_rate |
Сессий с одного IP за час | 10 |
device_rate |
Сессий с одного устройства за час | 5 |
ip_numbers |
Разных номеров с одного IP за сутки | 5 |
ip_country |
IP из страны вне списка разрешённых | Разрешены все |
ip_blocked |
IP в общем блоклисте VERYO | — |
{"error": "fraud_blocked", "reason": "ip_rate", "message": "Слишком много запросов кода с этого IP за час."}
Правила по IP и устройству работают, только если вы передаёте signals.ip и signals.device_id.