crontap-retries-and-idempotency

Retries and 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.

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.

1. 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.

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.

MCP examples

Inspect failures before changing policy:

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

Retry common transient classes:

{
  "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.

Endpoint idempotency pattern

Use a unique database constraint or atomic insert keyed by a logical job identity:

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.

REST fallback

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>.

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.

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.

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.

References

• Crontap Agent Skills catalogue
• Automatic retries with exponential backoff
• Cron troubleshooting
• Cron job monitoring
• Live REST API reference
• Machine-readable product reference