Novu Framework Bridge Endpoint的重试策略：哪些HTTP状态码会触发3次重试-平芜编程栈

Novu Framework Bridge Endpoint的重试策略：哪些HTTP状态码会触发3次重试

【免费下载链接】novuThe open-source communication infrastructure for agents and products项目地址: https://gitcode.com/GitHub_Trending/no/novu

用 Novu Framework 构建 code-first 工作流时，你的应用必须暴露一个 Bridge Endpoint（单个 HTTP 端点，例如/api/novu）给 Novu 的 Worker Engine 调用，用来执行框架步骤、解析步骤内容。端点偶发挂掉或返回错误时，Novu 是否会自动重试，取决于你返回的 HTTP 状态码或发生的网络错误类型。这篇文章回答三件事：哪些状态码会触发 3 次重试、每次重试的延迟是多少、以及如何确认你的 bridge 端点与这套重试策略正确配合。

适用范围：只针对用 Novu Framework 构建的工作流（code-first workflows）。在 Dashboard 中构建的工作流运行在 Novu 内部托管的共享 bridge 端点上，你不需要暴露、配置或知道那个 URL，也就无需关注本文的重试配置。

哪些 HTTP 状态码会触发 3 次重试

当 Novu 调用你的 bridge endpoint 执行框架步骤时，瞬时失败（transient failures）会在步骤被标记为失败之前自动重试，最多3 次，采用指数退避，公式为2^attemptCount × 500ms：

重试	延迟
第 1 次	1 秒
第 2 次	2 秒
第 3 次	4 秒

会触发重试的HTTP 状态码为：408、429、500、503、504、521、522、524。

会触发重试的瞬时网络错误码（文档以 "such as" 列举）包括EAI_AGAIN、ECONNREFUSED、ECONNRESET、ETIMEDOUT、ENOTFOUND。注意两份文档列举略有差异：Bridge Endpoint 文档列出了包含EAI_AGAIN的完整清单，而重试策略参考页只列了后四个；两者都说明这是举例而非穷举。

不会触发重试的响应：除408和429之外的大多数4xx错误。也就是说，400、404这类确定性错误返回后，Novu 不会重试，步骤直接进入失败处理。

另外，每个 bridge 请求有5 秒超时；3 次重试全部耗尽后，该步骤才会被标记为失败。

容易混淆：其他层的重试行为不一样

理解"bridge 端点的 3 次重试"时，最容易踩的坑是把 provider 发送和 webhook 的重试策略混为一谈。Novu 在投递链路的几个位置各有独立的策略（见 delivery-retries.mdx）：

层	是否自动重试	次数	退避
渠道步骤发送到 provider（Email/SMS/Chat/Push）	否	1 次调用	-
Bridge endpoint 调用（Framework）	是	3 次重试	`2^attempt × 500ms`，上限 4 秒
Novu 发出的出站 webhook	是	8 次	固定时间表，约 27.5 小时，上限 10 小时

由此得出两条对排障很关键的结论：

provider 拒绝一律是终态。如果 SendGrid、Twilio 或 FCM 返回429或503，处理方式与400完全相同——记录Unexpected provider error执行详情（Failed 状态，附带 provider 原始响应）、发出messages.failedwebhook、在 Activity Feed 中标记步骤失败，然后继续工作流下一步。provider 侧的瞬时故障不会重试，受影响的工作流运行会永久未投递。
唯一例外的 provider 是 Email Webhook：它会向配置的 webhook URL 最多重新 POST3 次，尝试之间固定30 秒延迟，之后才失败步骤。这是 provider 特有行为，不是平台策略。

所以同一个429，从你的 bridge 端点返回会被重试 3 次，从 provider 返回则直接失败。

准备：让 bridge 端点跑起来

核对重试策略之前，先按 Bridge Endpoint 文档和 Express 快速上手把端点搭好，用于后续验证。

安装 Framework 包：

npm install @novu/framework

在应用中挂载 bridge 端点。Novu 为 Express、Next.js、NestJS、Nuxt、h3、Hono、Remix、Sveltekit、AWS Lambda 提供框架专属的serve封装，它会处理GET/POST/PUT/OPTIONS请求解析、HMAC header 认证和框架特定的响应处理。Express 示例：

app.use(express.json()); // Required for Novu POST requests app.use("/api/novu", serve({ workflows: [testWorkflow] }));

端点路径不限于/api/novu，可以任意，但路径必须包含在 bridge URL 中（bridge URL = 应用基础 URL + 端点路径）。

配置 Novu secret key（本地开发写入.env）：

NOVU_SECRET_KEY=your_secret_key

your_secret_key替换为你在 Novu Dashboard 获取的 secret key。

启动应用。本地开发运行npx novu dev打开 Novu Dashboard 的 Local 模式；如果你的 Express 应用端口不是4000，用npx novu@latest dev --port <YOUR_EXPRESS_JS_APPLICATION_PORT>重启 dev 命令。生产环境则部署应用，确保端点可被公网访问——bridge URL 必须公开可达，且文档建议为 bridge URL 启用 https。

验证：注册 bridge URL 并确认状态

将 bridge URL 同步到目标环境（CLI 文档）：

npx novu@latest sync \ --bridge-url <YOUR_DEPLOYED_URL_WITH_BRIDGE_ENDPOINT> \ --secret-key <NOVU_SECRET_KEY> \ --api-url https://api.novu.co

其中<YOUR_DEPLOYED_URL_WITH_BRIDGE_ENDPOINT>替换为你已部署应用的 bridge 完整 URL。例如应用运行在https://api.domain.com且/api/novu端点提供 Novu 工作流，则填https://api.domain.com/api/novu。如果应用在 Novu Cloud 的 EU 区域，把--api-url换成https://eu.api.novu.co。本地开发时可以用npx novu dev生成的 tunnel URL（形如https://<UUID>.novu.sh/api/novu）作为该值。

查看同步输出。成功时打印从 bridge endpoint 发现的 workflows 和 steps 数量（以下为例文档中的示例结果，数值以你实际输出为准）：

{"status":"ok","sdkVersion":"2.10.0","frameworkVersion":"2024-06-26","discovered":{"workflows":14,"steps":30}}

若同时看到Could not discover agents for bridge URL sync (bridge may not expose agents yet).，这是信息提示而非错误，只表示 bridge 未在 sync 端点暴露 Agents，工作流与步骤仍然同步成功。

在 Dashboard 确认连接状态。打开对应环境（Development 或 Production），点击右上角导航栏Publish changes旁边发光的 status orb（只有该环境已设置 bridge URL 时才会出现），点开后可以看到Bridge Endpoint URL弹出层，查看或更新 URL。orb 颜色反映连接健康：绿色表示端点响应成功，红色表示不可达。

触发一次测试工作流，验证端点端到端可用。可以从 Local 环境触发，或用 Novu API：

curl -X POST https://api.novu.co/v1/events/trigger \ -H 'Authorization: ApiKey YOUR_API_KEY' \ -H 'Content-Type: application/json' \ \ -d '{ "name": "my-workflow", "to": "subscriber-id", "payload": {} }'

YOUR_API_KEY替换为你的 Novu API key，name是你的工作流名，to是订阅者标识——以上占位值来自 Express 快速上手文档的原始示例。触发后应能在 Local 环境中看到通知被处理。

关于失败路径的验证：当 bridge 请求失败且 3 次重试耗尽后，步骤在 Activity Feed 中被标记为失败，失败记录（含 provider 错误信息，如适用）就留在 Activity Feed 中。Novu 没有可检查的 dead-letter queue，Activity Feed 和messages.failedwebhook 就是失败投递的记录。需要留意：失败的渠道步骤不会中断工作流，后续步骤照常排队执行；而失败的action步骤（digest、delay、throttle）会终止该次运行，该订阅者剩余步骤全部取消。

限制与边界

各层的尝试次数与退避是固定的，不能按 workflow、step 或 integration 配置。你的端点能做的是选择正确的状态码：瞬时故障落在408/429/500/503/504/521/522/524区间内才会被 Novu 重试，其余4xx会立即失败步骤。
每个 bridge 请求 5 秒超时，端点内耗时较长的逻辑需要自行控制。
重试策略的完整出处见 Retry behavior 与 Delivery Retry Policy；本地开发的更多细节见 Local development。