API 幂等性
在公共 API POST 请求中发送 Idempotency-Key header,重试时便会返回首次成功的响应,而不会再次运行请求。
提示
Feature availability 功能可用性
n8n API 幂等性从 n8n 2.45.0 起可用于:
- n8n Cloud: Starter、Pro、Enterprise
- Self-hosted: 所有版本
免费试用期间无法使用。
此 header 为可选项。如果省略,每个 POST 请求都会照常运行。
发送幂等性 key
在首次 POST 请求中设置 Idempotency-Key header,并在重试时再次发送相同的 header。每个不同的请求都应使用新的 key。版本 4 UUID 是一个安全的选择,但 n8n 不要求使用此格式。
该值必须包含 1 到 128 个可见 ASCII 字符,包括字母、数字和符号,不得包含空格。n8n 会忽略 key 前后的空格。空值或仅包含空格的值等同于省略此 header。
curl -X POST \
'https://<your-instance>/api/v1/workflows' \
-H 'accept: application/json' \
-H 'X-N8N-API-KEY: <your-api-key>' \
-H 'Idempotency-Key: <idempotency-key>' \
-H 'Content-Type: application/json' \
-d '<workflow-json>'
将 <workflow-json> 替换为工作流 body。有关如何创建 API key,请参阅身份验证。
如果 key 过长、包含空格或其他不允许的字符,请求会返回 400,且不会创建资源。消息为 Idempotency-Key must be 1 to 128 visible ASCII characters.
使用此 key 的请求
n8n 会在创建内容或启动工作的 POST 请求中使用此 header,例如创建工作流或调用 POST /api/v1/executions/<execution-id>/retry。端点参考会在每个支持此 header 的 POST 请求中显示它。
n8n 会忽略 GET、PUT、PATCH 和 DELETE 请求中的此 header。
n8n 保留响应的时长
n8n 会从你发送 key 时起保留首次成功响应 12 小时。在此时间窗内重试会返回该响应,而不会再次运行 POST 请求。
12 小时后,使用相同 key 会再次运行 POST 请求,并可能创建重复内容。请为下一项操作发送新的 key。
key 属于用户,而不是某一个 API key。同一用户的两个 API key 共享已存储的响应。不同用户发送的相同 key 会被视为单独的请求。
重试相同请求
再次发送相同的 key、path、query string 和 body,包括相同的 JSON 字段顺序和所有空格。匹配时会返回与首次响应相同的状态码和 JSON body。
返回文件的 POST 请求不在此机制的覆盖范围内。重试时会再次运行该请求。
相同 key,不同请求
如果 path、query string 或 body 不同,n8n 会返回 422,且不会运行 POST 请求:
{
"message": "This Idempotency-Key was already used with a different request."
}
请为更改后的请求发送新的 key。首次创建的资源保持不变。
请求仍在进行中
如果首次请求尚未完成,n8n 会返回 409:
{
"message": "A request with this Idempotency-Key is already in progress."
}
请等待一段时间,然后使用相同 key 再次发送相同请求。使用同一个 key 同时发送两个请求不会创建两个资源。其中一个请求会完成工作;另一个请求会收到 409,如果首个请求已经完成,则会收到首次响应。
请求失败时
如果 POST 请求失败,n8n 不会保留该响应。使用相同 key 重试相同请求时,会再次运行 POST 请求。
如果首次 POST 请求因 body 无效而返回 400,请修正 body,然后再次发送相同的 key。
幂等性 key 的限制
幂等性 header 仅适用于 /api/v1 下的公共 API 端点。