Коды ответов
200 / 202
запрос принят. 202 — сообщение поставлено в очередь,
а не доставлено
400
неверный номер, пустой текст или превышена длина
400 not_mobile
городской номер — СМС туда не доставляется.
Пропустите его, рассылку продолжать можно: на анти-бан это не влияет
401
нет или неверен X-API-Key
429
оператор отклонил отправку — прервите рассылку,
в поле retry_after_s сколько ждать
503
reason=modem_down — модем не отвечает, отправка
приостановлена. Очередь цела, сообщения дождутся. Переждите
retry_after_s и повторите
503
очередь переполнена, повторите позже
🛡️ Как не потерять сообщения и не поймать блокировку
Главное, что нужно заложить в интеграцию. Устройство
само сообщает, когда отправлять нельзя — задача вашего сервиса эти
ответы обрабатывать, а не игнорировать.
429
Оператор отклонил отправку. Немедленно прервите
рассылку до конца паузы (retry_after_s).
Продолжать — прямой путь к блокировке SIM
503 modem_down
Модем не отвечает. Приостановите отправку и
повторяйте раз в 30 с. Всё, что уже в очереди, сохранено и уйдёт
после восстановления — но новое принимать устройство не может
503 throttle_pause
Плановая пауза анти-бана (после каждых N
сообщений). Подождите retry_after_s —
отправка возобновится сама. Не ждать нельзя: за паузу очередь
переполнится и сообщения начнут отклоняться
503 queue_full
Очередь заполнена (64). Притормозите и повторите
то же самое сообщение, а не следующее
503 quiet_hours
Ночная тишина. Реклама и уведомления ждут утра.
Срочное шлите с type=system — оно уходит
круглосуточно
503 daily_limit
Исчерпан суточный потолок. Обнуляется в
00:00 по местному времени устройства;
type=system потолок не расходует
Исходящие. Ответ 202 означает «принято
в очередь», а не «доставлено». Если модем отвалится, сообщения из
очереди не пропадут — отправка встанет на паузу и продолжится
сама. Сохраняйте uid из ответа: он же
дописан в текст сообщения.
Очередь конечна — 64 сообщения. Она сглаживает интервалы, но не
рассчитана на тысячи: у устройства для этого нет памяти. Правило
простое — получили любой 503, дождитесь
retry_after_s и повторите то же сообщение.
В каждом успешном ответе есть queue_free:
если оно близко к нулю, сбавьте темп заранее.
Входящие. Сообщение удаляется с устройства только после того,
как ответ дошёл до вас. Оборвётся связь — придёт снова в следующем
запросе. Поэтому отсеивайте дубликаты по id:
лучше повтор, чем потеря. Нужна полная строгость — работайте через
ack=0 с явным подтверждением.
Городские номера отсеиваются сами. На стационарную линию
(+7 495, +7 812)
СМС не доходит, а сеть отвечает отказом без кода ошибки —
неотличимо от антиспам-фильтра. Такие номера отклоняются сразу с
400 not_mobile и не засчитываются
в срабатывание анти-бана.
Список кодов настраивается в Настройках → Номера, куда СМС не
доставляется: по умолчанию 3,4,8
(Урал и Сибирь, Северо-Запад с Дальним Востоком, сервисные).
Мобильные 9xx и иностранные номера не
трогаются.
Память SIM всего 15 сообщений. Когда она заполнена, сеть
перестаёт доставлять новые входящие. Устройство чистит её само, но
забирайте сообщения регулярно и следите за
mem_used.
Перезагрузка и пропадание питания. Очередь отправки и входящие
хранятся во flash-памяти устройства. После рестарта — по питанию,
после обновления прошивки или из-за сбоя — принятые, но не
отправленные сообщения досылаются автоматически, а входящие
остаются на месте. В журнале это видно строкой «Восстановлено
неотправленных СМС».
Возможен повтор: если питание пропало между отправкой в эфир и
отметкой в журнале, сообщение уйдёт второй раз с тем же
uid. Так сделано намеренно — повтор
отслеживается по uid, а пропажу восстановить нечем.
Обрыв Wi-Fi. Отправка СМС не зависит от сети: модем работает
сам по себе, и очередь продолжает уходить в эфир, пока интернета нет.
Недоступен только приём новых заданий по API. Устройство
переподключается к Wi-Fi бесконечно, раз в 10 секунд.
