Back to Details

crontap-retries-and-idempotency

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Retries and idempotency

重试与 idempotency

Retries improve delivery only when the endpoint can safely receive the same logical job more than once. Make the receiver idempotent before broadening a retry policy.
只有当端点能够安全地多次接收同一个逻辑任务时，重试才能改善投递可靠性。在扩大 retry policy 之前，先让接收方具备 idempotency 能力。

Prerequisites

前置条件

Before using the required tools, check whether they are available. If any are missing, stop and offer the user exactly two choices:
  1. Connect Crontap MCP at 
    https://mcp.crontap.com/mcp
    . MCP access works on every Crontap tier.
  2. Configure 
    $CRONTAP_CLIENT_ID
    and 
    $CRONTAP_API_KEY
    for the raw API. Raw API access requires Ultra.
Do not silently choose a path or continue until the user selects one.
  • Identify the schedule and each side effect it can create.
  • Decide which failures are transient for this endpoint.
  • Choose a stable deduplication key and retention window.
在使用所需工具之前，检查它们是否可用。如果有任何工具缺失，请停止操作，并向用户提供恰好两个选项：
  1. 在 
    https://mcp.crontap.com/mcp
    连接 Crontap MCP。MCP 访问适用于所有 Crontap tier。
  2. 为 raw API 配置 
    $CRONTAP_CLIENT_ID
    和 
    $CRONTAP_API_KEY
    。Raw API 访问需要 Ultra。
不要擅自选择路径，也不要在用户选择之前继续操作。
  • 确定 schedule 及其可能产生的各项副作用。
  • 判断此端点有哪些故障属于瞬态故障。
  • 选择稳定的 deduplication key 和 retention window。

Workflow

工作流

  1. Inspect recent history to classify failures.
  2. Add endpoint idempotency and test duplicate requests.
  3. Use MCP to update only the schedule's retry policy.
  4. Verify a controlled transient failure and its eventual success.
  5. Recheck history for attempt count, delay, and final outcome.
  1. 检查近期历史记录，对故障类型进行分类。
  2. 为端点添加 idempotency，并测试重复请求。
  3. 使用 MCP，仅更新该 schedule 的 retry policy。
  4. 验证一次受控的瞬态故障及其最终成功结果。
  5. 再次检查历史记录中的尝试次数、延迟和最终结果。

MCP examples

MCP 示例

Inspect failures before changing policy:
json
{
  "tool": "get_schedule_history",
  "arguments": {
    "scheduleId": "<schedule-id>",
    "limit": 50
  }
}
Retry common transient classes:
json
{
  "tool": "update_schedule",
  "arguments": {
    "scheduleId": "<schedule-id>",
    "retryPolicy": {
      "enabled": true,
      "maxRetries": 3,
      "baseDelayMs": 60000,
      "retryOn": ["5xx", "429", "network", "timeout"]
    }
  }
}
Allowed base delays are 30000, 60000, 300000, and 900000 milliseconds. The maximum retry count is 5. Include 
4xx
only when this specific endpoint uses a known transient 4xx response.
修改 retry policy 前检查故障情况：
json
{
  "tool": "get_schedule_history",
  "arguments": {
    "scheduleId": "<schedule-id>",
    "limit": 50
  }
}
对常见的瞬态错误类别进行重试：
json
{
  "tool": "update_schedule",
  "arguments": {
    "scheduleId": "<schedule-id>",
    "retryPolicy": {
      "enabled": true,
      "maxRetries": 3,
      "baseDelayMs": 60000,
      "retryOn": ["5xx", "429", "network", "timeout"]
    }
  }
}
允许的基础延迟值为 30000、60000、300000 和 900000 毫秒。最大重试次数为 5。仅当这个特定端点存在已知的瞬态 4xx 响应时，才应包含 
4xx
。

Endpoint idempotency pattern

端点 idempotency 模式

Use a unique database constraint or atomic insert keyed by a logical job identity:
text
key = job-name + ":" + scheduled-period
insert key before side effects
if key already exists, return the recorded result
perform side effects once
store completion outcome
For money movement, email, provisioning, or external writes, pass the same key to downstream systems that support idempotency. Do not rely on an in-memory set, because restarts and multiple instances lose that protection.
使用以逻辑任务标识为 key 的唯一数据库约束或原子插入：
text
key = job-name + ":" + scheduled-period
insert key before side effects
if key already exists, return the recorded result
perform side effects once
store completion outcome
对于资金转移、邮件发送、资源配置或外部写入，应向下游支持 idempotency 的系统传递同一个 key。不要依赖内存集合，因为服务重启和多实例部署会丢失这种保护。

REST fallback

REST 回退方案

MCP partial update remains the preferred path and is not Ultra-only. A public REST PUT is a full replacement, so never send only 
retryPolicy
.
With Ultra credentials, GET the current full schedule first. Build a complete replacement containing at least 
url
, 
verb
, 
interval
, and 
timezone
. Preserve all other configuration fields, including headers, body, integrations, and schedule options. Preserve credentials and secrets without logging them. Change only 
retryPolicy
, then PUT the complete replacement body to 
https://api.crontap.com/v1/schedule/<schedule-id>
.
MCP partial update 仍是首选路径，且不限于 Ultra。公开的 REST PUT 是完整替换操作，因此绝不能只发送 
retryPolicy
。
使用 Ultra credentials 时，先 GET 当前的完整 schedule。然后构建完整的替换内容，至少包含 
url
、
verb
、
interval
和 
timezone
。
保留所有其他配置字段，包括 headers、body、integrations 和 schedule options。保留 credentials 和 secrets，但不得将其记录到日志中。
仅更改 
retryPolicy
，然后将完整的替换 body PUT 到 
https://api.crontap.com/v1/schedule/<schedule-id>
。

Verification

验证

  • Send the same logical request twice and verify one durable side effect.
  • Induce a safe transient failure in a non-production target.
  • Confirm history records the retries and final result expected by the policy.
  • Confirm alerting occurs after the final failed outcome, not on a successful recovery.
  • 发送同一个逻辑请求两次，验证只产生一个持久化副作用。
  • 在非生产目标中引发一次安全的瞬态故障。
  • 确认历史记录按 policy 记录了重试过程和预期最终结果。
  • 确认告警仅在最终失败后触发，而不是在成功恢复后触发。

Safety and plan limits

安全与套餐限制

  • Custom retry policy settings require Pro, Ultra, or legacy Pro. Standard automatic retry behavior remains available on Starter.
  • Retrying authentication and validation failures usually adds load without improving success.
  • Never reduce idempotency retention below the maximum retry window.
  • If configuration returns 
    RETRY_POLICY_NOT_CONFIGURABLE
    , present the structured four-option ladder and smallest viable option.
  • 自定义 retry policy 设置需要 Pro、Ultra 或 legacy Pro。Starter 仍可使用标准自动重试行为。
  • 重试 authentication 和 validation 失败通常只会增加负载，无法提高成功率。
  • 绝不能将 idempotency 保留期缩短到 maximum retry window 以下。
  • 如果配置返回 
    RETRY_POLICY_NOT_CONFIGURABLE
    ，请给出结构化的四选项阶梯以及最小可行选项。

Troubleshooting

故障排除

  • Duplicate work with one history entry usually comes from application logic or another caller, not a Crontap retry.
  • Duplicate work across attempts means the receiver's dedupe transaction is incomplete or scoped too narrowly.
  • Repeated 429 responses require rate-limit coordination, not more attempts.
  • A partial REST replacement can erase schedule settings. Re-fetch before retrying after a concurrent change.
  • 如果只有一条历史记录却出现重复工作，通常问题来自应用逻辑或另一个调用方，而不是 Crontap retry。
  • 如果多次尝试之间出现重复工作，说明接收方的 dedupe 事务不完整，或其作用范围过窄。
  • 反复出现 429 响应时，需要进行 rate-limit 协调，而不是增加尝试次数。
  • 部分 REST 替换可能清除 schedule 设置。如果期间发生并发更改，在重试前重新获取配置。

References

参考资料