Ошибки обработчика вебхуков

Причина сбоя видна в истории доставки. Здесь описано, как Senler определяет категорию и какие данные может вернуть обработчик приложения.

Что требует внимания разработчика

В списке приложений у каждого приложения отдельно показываются два числа: сколько текущих инцидентов нужно проверить разработчику и сколько доставок не завершилось успешно за выбранный период. Это разные показатели. Историческая ошибка остаётся в статистике, даже если её уже рассмотрели, а счётчик «Проверить разработчику» содержит только нерешённые текущие инциденты. В API этот текущий счётчик возвращается как developer_attention вместе с соответствующим app_id.

Категория отвечает на вопрос, кто должен разбираться с причиной:

• Ошибка приложения (application). Обработчик приложения вернул ошибку или сообщил о сбое своей логики. Разработчик приложения проверяет обработчик.
• Настройка проекта (configuration). В установленном приложении конкретного проекта нет нужного аккаунта, доступа или другой настройки. Владелец или участник проекта исправляет настройку; это не ошибка кода приложения.
• Ошибка платформы (platform). Запрос не дошёл до приложения из-за сбоя доставки внутри Senler. Причину устраняет Senler; разработчику приложения ничего перенастраивать не нужно.
• Причина не определена (unknown). Ответа недостаточно для надёжной классификации. Разработчик проверяет запрос и ответ вручную.

application и unknown получают developer_action_required: true и входят в счётчик проверки разработчиком. configuration и platform получают developer_action_required: false и в этот счётчик не входят.

Как определяется категория

Senler классифицирует не по одному HTTP-коду и не по тексту ошибки. Используется следующий порядок:

1. Если доставка завершилась до вызова внешнего обработчика, инцидент относится к platform.
2. Если обработчик вернул корректный объект incident, Senler использует объявленную приложением категорию application или configuration.
3. Если объекта incident нет, ответ 5xx считается application.
4. Остальные необъяснённые ошибки считаются unknown.

Поле code не выбирает категорию автоматически. Это стабильный технический идентификатор причины внутри уже определённой категории. Поле retryable отдельно указывает, имеет ли смысл повторять запрос без исправления его данных. Для ответа без объекта incident значение выводится из результата доставки — сетевой ошибки, тайм-аута или HTTP-статуса. В истории запросов API возвращает итоговый incident с полями code, category, developer_action_required и retryable. У ручного повтора есть дополнительное исключение для ответов внешнего обработчика 401 и 403 — оно описано ниже.

Как приложению вернуть точную причину

Чтобы Senler не пытался угадать причину по HTTP-ответу, обработчик приложения может вернуть безопасный JSON с объектом incident. Например, инструмент оплаты не нашёл выбранный пользователем аккаунт в настройках проекта:

{
  "message": "Configured Prodamus account is unavailable",
  "incident": {
    "code": "prodamus_account_unavailable",
    "category": "configuration",
    "retryable": false
  }
}

Контракт объекта:

• code — необязательный постоянный машинный код причины: от 1 до 128 символов, начинается с латинской буквы или цифры и далее содержит только строчные латинские буквы, цифры, ., _ или -; отсутствующий или некорректный код сохраняется как null, но не отменяет категорию;
• category — только application или configuration; категории platform и unknown назначает сам Senler;
• retryable — true, только если повтор того же payload без изменения данных действительно безопасен и может помочь;
• developer_action_required приложение не передаёт — Senler вычисляет его по категории.

category и логическое значение retryable обязательны. Если одно из них отсутствует или недопустимо, Senler игнорирует объявленный объект и применяет обычную классификацию по источнику сбоя и HTTP-статусу.

Текст message нужен человеку, а incident.code — агенту, логам и автоматической диагностике. Не помещайте в них секреты, токены, персональные данные или внутренний stack trace. Если проблема вызвана выбранным аккаунтом или настройкой конкретной установки, используйте configuration; если сломана логика обработчика самого приложения — application.

После исправления причины используйте повторную доставку или закрытие инцидента.