Learn more about retry strategies in the Alert Retries overview.
Use retry strategies to configure automatic retries for failed check runs. This helps reduce false positives and ensures that temporary network issues don’t trigger unnecessary alerts.
Before configuring retry strategies, ensure you have:
  • An initialized Checkly CLI project
  • Understanding of your service’s reliability characteristics and expected failure patterns
  • Knowledge of appropriate retry intervals for your specific use case
  • Awareness of how retries affect alert timing and incident response workflows
For additional setup information, see CLI overview.
import { ApiCheck, RetryStrategyBuilder } from "checkly/constructs"

new ApiCheck("retrying-check", {
  name: "Check With Linear Retries",
  retryStrategy: RetryStrategyBuilder.linearStrategy({
    baseBackoffSeconds: 30,
    maxRetries: 4,
    sameRegion: false,
  }),
  request: {
    method: "GET",
    url: "https://api.example.com/health",
  },
})

​
Configuration

​
Retry Strategy Methods

Use the RetryStrategyBuilder methods to apply different retry strategies to your checks and monitors.
MethodDescriptionUse Case
noRetries()No retries are performedChecks that should fail fast
fixedStrategy(options)Fixed time between retries (e.g., 5s, 5s, 5s)Predictable retry intervals
linearStrategy(options)Linearly increasing intervals (e.g., 5s, 10s, 15s)Gradual backoff
exponentialStrategy(options)Exponentially increasing intervals (e.g., 5s, 25s, 125s)Aggressive backoff for overloaded services
​
noRetries()
method
Disables all retries for a check. When a check fails, it immediately triggers an alert without attempting any retries.Usage:
// Critical endpoint that should alert immediately
new ApiCheck("critical-endpoint", {
  name: "Critical Payment API",
  retryStrategy: RetryStrategyBuilder.noRetries(),
  request: {
    method: "GET",
    url: "https://api.example.com/payments/health",
  },
})
Use cases: Critical services requiring immediate alerting, security endpoints, fail-fast scenarios.
​
fixedStrategy(options)
method
Retries with fixed intervals between attempts. Each retry waits the same amount of time as specified by baseBackoffSeconds.Time between retries with five seconds baseBackoffSeconds and three retries: 5s, 5s, 5s.Usage:
// Stable API with predictable retry pattern
new ApiCheck("stable-api", {
  name: "Stable API Endpoint",
  retryStrategy: RetryStrategyBuilder.fixedStrategy({
    baseBackoffSeconds: 30, // Wait 30s between retries
    maxRetries: 2,
    sameRegion: true,
  }),
  /* More options... */
})
// Retry pattern: 30s, 30s (total: ~60s)
Use cases: Stable services, predictable retry timing, simple backoff requirements.
​
linearStrategy(options)
method
Retries with linearly increasing intervals. Each subsequent retry waits longer: baseBackoffSeconds × retry_number.Time between retries with five seconds baseBackoffSeconds and three retries: 5s, 10s, 15s.Usage:
// API with gradual backoff strategy
new ApiCheck("gradual-backoff", {
  name: "API with Gradual Backoff",
  retryStrategy: RetryStrategyBuilder.linearStrategy({
    baseBackoffSeconds: 15, // First retry after 15s
    maxRetries: 3,
    sameRegion: false, // Try different regions
  }),
  /* More options... */
})
// Retry pattern: 15s, 30s, 45s (total: ~90s)
Use cases: Services that need time to recover, moderate backoff requirements, regional issue detection.
​
exponentialStrategy(options)
method
Retries with exponentially increasing intervals. Each retry waits exponentially longer: baseBackoffSeconds^retry_number.Time between retries with five seconds baseBackoffSeconds and three retries: 5s, 25s, 125s.Usage:
// Service that might be overloaded
new ApiCheck("overloaded-api", {
  name: "Potentially Overloaded API",
  retryStrategy: RetryStrategyBuilder.exponentialStrategy({
    baseBackoffSeconds: 5, // First retry after 5s
    maxRetries: 3,
    maxDurationSeconds: 300, // Stop after 5 minutes total
    sameRegion: true,
  }),
  /* More options... */
})
// Retry pattern: 5s, 25s, 125s
Use cases: Overloaded services, rate-limited APIs, aggressive backoff scenarios, circuit breaker patterns.

​
Retry Strategy Options

​
baseBackoffSeconds
number
default:"60"
Time to wait before the first retry attempt. Also used as the base value for calculating subsequent retry intervals in linear and exponential strategies.Usage:
// Quick retries for fast services
RetryStrategyBuilder.fixedStrategy({
  baseBackoffSeconds: 30, // Fixed: 30s, 30s, 30s
})

// Slower retries for heavy operations
RetryStrategyBuilder.linearStrategy({
  baseBackoffSeconds: 10, // Linear: 10s, 20s, 30s
})

// Very quick retries for lightweight checks
RetryStrategyBuilder.exponentialStrategy({
  baseBackoffSeconds: 5, // Exponential: 5s, 25s, 125s
})
​
maxRetries
number
default:"2"
Maximum number of retry attempts after the initial failure. The total number of check attempts will be maxRetries + 1.Usage:
RetryStrategyBuilder.linearStrategy({
  maxRetries: 3, // 3 retry attempts after initial failure
})
Range: 1-10 retries
​
maxDurationSeconds
number
default:"600"
Maximum total time to spend on all retry attempts. If the calculated retry schedule would exceed this duration, retries stop early. The maximum value is 600 seconds (10 minutes).Usage:
RetryStrategyBuilder.exponentialStrategy({
  maxDurationSeconds: 300, // Stop retrying after 5 minutes total
})
​
sameRegion
boolean
default:"true"
Whether retry attempts should run from the same region as the original failed check, or from different regions to help identify regional issues.Usage:
RetryStrategyBuilder.linearStrategy({
  sameRegion: false, // Try different regions for retries
})
When sameRegion: false, retries are attempted from different regions to help distinguish between regional networking issues and actual service problems.
Use cases: Regional issue detection, network diversity, consistency testing.

​
Examples

import { ApiCheck, RetryStrategyBuilder } from "checkly/constructs"

new ApiCheck("fail-fast-check", {
  name: "Fail Fast Check",
  retryStrategy: RetryStrategyBuilder.noRetries(),
  request: {
    method: "GET",
    url: "https://api.example.com/critical-endpoint",
  },
})

​
Best Practices

// For stable APIs - minimal retries
const stableApiRetry = RetryStrategyBuilder.fixedStrategy({
  baseBackoffSeconds: 30,
  maxRetries: 2,
  sameRegion: true,
})

// For unstable APIs - more aggressive retries
const unstableApiRetry = RetryStrategyBuilder.exponentialStrategy({
  baseBackoffSeconds: 10,
  maxRetries: 4,
  sameRegion: false,
})