Skip to Content
СправочникОшибки API и dunning

Ошибки API и dunning

Формат ошибок

REST API BillBill (GoFrame) обычно возвращает JSON с полями вроде code, message, иногда data. Клиент @wilix/billbill-client-js мапит это в BillBillError.

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

  • Логируйте code и тело ответа при 4xx/5xx.
  • Различайте ошибки валидации (исправить запрос) и временные сбои (ретрай с backoff).

Лимиты облака

Конкретные rate limit и квоты зависят от договора. При массовой отправке metricNewEvent согласуйте пики с поддержкой BillBill.

Dunning и неуспешная оплата

При автопродлении подписки счёт цикла может остаться неоплаченным. В коде API существует пайплайн обхода биллингового цикла (SubPipeBillingCycleWalk и связанные задачи):

  • обработка просроченных подписок в статусе создания;
  • сценарии отмены/истечения при отсутствии оплаты в оговорённые сроки;
  • напоминания через исходящие вебхуки (subscription.latest_invoice.track, subscription.auto_renew.failure и др.).

Точные таймауты (например, 48 часов на первую оплату) и политика повторных попыток списания зависят от версии API и настроек мерчанта — зафиксируйте их для своего окружения по Swagger и по ответам поддержки.

Что делать интегратору

  1. Подписаться на payment.failure, invoice.failed, subscription.auto_renew.failure.
  2. В своём продукте включать grace period или ограничение доступа по политике SaaS.
  3. Предлагать пользователю обновить способ оплаты (через ваш UI + вызовы API смены метода оплаты, если доступны).
События вебхуков