crontap-retries-and-idempotency

再試行と冪等性

再試行によって配信が改善するのは、同じ論理ジョブを複数回安全に受け取れるエンドポイントに限られます。再試行ポリシーを広げる前に、受信側を冪等にしてください。

前提条件

必須ツールを使用する前に、利用可能かどうかを確認してください。利用できないツールがある場合は処理を中止し、ユーザーに次の2つの選択肢だけを提示してください。

1. https://mcp.crontap.com/mcp で Crontap MCP に接続します。MCP はすべての Crontap プランで利用できます。
2. 生の API を使用するために、$CRONTAP_CLIENT_ID と $CRONTAP_API_KEY を設定します。生の API の利用には Ultra が必要です。

ユーザーが選択するまでは、黙って経路を選んだり、処理を続行したりしないでください。

• スケジュールと、スケジュールによって発生する各副作用を特定します。
• このエンドポイントで一時的とみなす障害を決定します。
• 安定した重複排除キーと保持期間を選びます。

ワークフロー

1. 直近の履歴を調べて、障害を分類します。
2. エンドポイントに冪等性を実装し、重複リクエストをテストします。
3. MCP を使って、スケジュールの再試行ポリシーのみを更新します。
4. 制御された一時的な障害と、その後の成功を確認します。
5. 履歴を再確認して、試行回数、遅延、最終結果を確認します。

MCP の例

ポリシーを変更する前に障害を調べます。

{
  "tool": "get_schedule_history",
  "arguments": {
    "scheduleId": "<schedule-id>",
    "limit": 50
  }
}

一般的な一時的障害クラスを再試行します。

{
  "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 を含めてください。

エンドポイントの冪等性パターン

論理ジョブの識別情報をキーとして、一意制約またはアトミックな挿入を使用します。

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

資金移動、メール送信、プロビジョニング、外部への書き込みでは、冪等性に対応する下流システムにも同じキーを渡してください。インメモリのセットには依存しないでください。再起動や複数インスタンスによって、その保護が失われるためです。

REST の代替手段

MCP の部分更新が引き続き推奨される方法であり、Ultra 限定ではありません。公開 REST の PUT は全置換なので、retryPolicy だけを送信しないでください。

Ultra の認証情報を使用して、まず現在のスケジュール全体を GET します。url、verb、interval、timezone を含む完全な置換内容を作成してください。ヘッダー、本文、インテグレーション、スケジュールオプションなど、その他すべての設定フィールドを保持してください。認証情報とシークレットはログに記録せず、そのまま保持してください。retryPolicy のみを変更し、完全な置換本文を https://api.crontap.com/v1/schedule/<schedule-id> に PUT します。

検証

• 同じ論理リクエストを2回送信し、永続的な副作用が1回だけ発生することを確認します。
• 本番以外のターゲットで、安全な一時的障害を発生させます。
• ポリシーで想定される再試行と最終結果が履歴に記録されていることを確認します。
• 成功して復旧した場合ではなく、最終的に失敗した場合にアラートが発生することを確認します。

安全性とプランの制限

• カスタム再試行ポリシーの設定には Pro、Ultra、またはレガシー Pro が必要です。Starter でも、標準の自動再試行動作は引き続き利用できます。
• 認証エラーや検証エラーを再試行しても、通常は負荷が増えるだけで成功率は向上しません。
• 冪等性の保持期間を、最大再試行期間より短くしないでください。
• 設定時に RETRY_POLICY_NOT_CONFIGURABLE が返された場合は、4つの選択肢からなる段階的な選択肢と、実行可能な最小の選択肢を提示してください。

トラブルシューティング

• 履歴エントリが1つしかないのに作業が重複する場合、通常は Crontap の再試行ではなく、アプリケーションのロジックまたは別の呼び出し元が原因です。
• 試行をまたいで作業が重複する場合、受信側の重複排除トランザクションが不完全であるか、適用範囲が狭すぎます。
• 429 応答が繰り返される場合、試行回数を増やすのではなく、レート制限を調整する必要があります。
• REST の部分置換によってスケジュール設定が消去されることがあります。並行変更後に再試行する前に、設定を再取得してください。

参考資料

• Crontap Agent Skills カタログ
• 指数バックオフによる自動再試行
• Cron のトラブルシューティング
• Cron ジョブの監視
• ライブ REST API リファレンス
• 機械可読な製品リファレンス