Delivery and errors

Delivery is at least once

A recurring delivery may arrive more than once after worker recovery or a retryable failure. Every request includes a stable Cronbolt-Run-Id header. Store that value before applying a non-idempotent effect.

New jobs retry network failures, timeouts, HTTP 408, HTTP 425, HTTP 429, and HTTP 5xx responses twice by default. The first retry waits 30 seconds, then the delay grows exponentially. Set max_retries to 0 to disable retries.

Cronbolt prevents overlapping deliveries for the same job. If a recurring occurrence becomes due while prior work is queued or running, Cronbolt records the new occurrence as skipped.

The default success check accepts HTTP 200 through 299. Jobs can narrow that range and require response text. Cronbolt evaluates response text in memory and never stores the response body. An application-level mismatch is retryable.

An optional alert webhook receives best-effort, secret-free failure and recovery events.

After downtime, Cronbolt does not replay a burst of old callbacks. The first materialized run includes coalesced_missed_count and coalesced_window_ends_at so the gap remains visible. Counts are exact up to 10,000; that value with a later window end means the safety cap was reached.

Polling runs

Manual run and retry responses include Location and Retry-After headers. Wait for the stated number of seconds, then fetch the Location until the run reaches a terminal state.

Error shape

Public API errors include:

{
  "code": "invalid_schedule",
  "message": "Enter a valid 5-field cron expression.",
  "request_id": "request identifier"
}

Validation errors also include errors. Rate limits include Retry-After. If action_url is present, open it for the developer rather than guessing how to resolve the account limit.

Callback safety

V1 accepts public http:80 and https:443 targets. It rejects localhost, private networks, unsafe ports, embedded credentials, unsafe headers, and DNS results that change to a private address.

Run history does not return callback headers, request bodies, response bodies, or raw exception text.