OpenParable
Skip to content
← Back to skills

Effect Patterns Error Handling Resilience

Development
effect-patterns-error-handling-resilience

Effect Patterns Error Handling Resilience is an Agent Skill for development published in the PaulJPhilp/EffectPatterns repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Effect-TS patterns for Error Handling Resilience. Use when working with error handling resilience in Effect-TS applications.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/PaulJPhilp/EffectPatterns/blob/HEAD/config/.claude-plugin/plugins/effect-patterns/skills/effect-patterns-error-handling-resilience/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/effect-patterns-error-handling-resilience, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Effect-TS Patterns: Error Handling Resilience

This skill provides 1 curated Effect-TS patterns for error handling resilience. Use this skill when working on tasks related to:

  • error handling resilience
  • Best practices in Effect-TS applications
  • Real-world patterns and solutions

🟡 Intermediate Patterns

Scheduling Pattern 2: Implement Exponential Backoff for Retries

Rule: Use exponential backoff with jitter for retries to prevent overwhelming failing services and improve success likelihood through smart timing.

Good Example:

This example demonstrates exponential backoff with jitter for retrying a flaky API call.

import { Effect, Schedule } from "effect";

interface RetryStats {
  readonly attempt: number;
  readonly delay: number;
  readonly lastError?: Error;
}

// Simulate flaky API that fails first 3 times, succeeds on 4th
let attemptCount = 0;

const flakyApiCall = (): Effect.Effect<{ status: string }> =>
  Effect.gen(function* () {
    attemptCount++;
    yield* Effect.log(`[API] Attempt ${attemptCount}`);

    if (attemptCount < 4) {
      yield* Effect.fail(new Error("Service temporarily unavailable (503)"));
    }

    return { status: "ok" };
  });

// Calculate exponential backoff with jitter
interface BackoffConfig {
  readonly baseDelayMs: number;
  readonly maxDelayMs: number;
  readonly maxRetries: number;
}

const exponentialBackoffWithJitter = (config: BackoffConfig) => {
  let attempt = 0;

  // Calculate delay for this attempt
  const calculateDelay = (): number => {
    const exponential = config.baseDelayMs * Math.pow(2, attempt);
    const withJitter = exponential * (0.5 + Math.random() * 0.5); // ±50% jitter
    const capped = Math.min(withJitter, config.maxDelayMs);

    yield* Effect.log(
      `[BACKOFF] Attempt ${attempt + 1}: ${Math.round(capped)}ms delay`
    );

    return Math.round(capped);
  };

  return Effect.gen(function* () {
    const effect = flakyApiCall();

    let lastError: Error | undefined;

    for (attempt = 0; attempt < config.maxRetries; attempt++) {
      const result = yield* effect.pipe(Effect.either);

      if (result._tag === "Right") {
        yield* Effect.log(`[SUCCESS] Succeeded on attempt ${attempt + 1}`);
        return result.right;
      }

      lastError = result.left;

      if (attempt < config.maxRetries - 1) {
        const delay = calculateDelay();
        yield* Effect.sleep(`${delay} millis`);
      }
    }

    yield* Effect.log(
      `[FAILURE] All ${config.maxRetries} attempts exhausted`
    );
    yield* Effect.fail(lastError);
  });
};

// Run with exponential backoff
const program = exponentialBackoffWithJitter({
  baseDelayMs: 100,
  maxDelayMs: 5000,
  maxRetries: 5,
});

console.log(
  `\n[START] Retrying flaky API with exponential backoff\n`
);

Effect.runPromise(program).then(
  (result) => console.log(`\n[RESULT] ${JSON.stringify(result)}\n`),
  (error) => console.error(`\n[ERROR] ${error.message}\n`)
);

Output demonstrates increasing delays with jitter:

[START] Retrying flaky API with exponential backoff

[API] Attempt 1
[BACKOFF] Attempt 1: 78ms delay
[API] Attempt 2
[BACKOFF] Attempt 2: 192ms delay
[API] Attempt 3
[BACKOFF] Attempt 3: 356ms delay
[API] Attempt 4
[SUCCESS] Succeeded on attempt 4

[RESULT] {"status":"ok"}

Rationale:

When retrying failed operations, use exponential backoff with jitter: delay doubles on each retry (with random jitter), up to a maximum. This prevents:

  • Thundering herd: All clients retrying simultaneously
  • Cascade failures: Overwhelming a recovering service
  • Resource exhaustion: Too many queued retry attempts

Formula: delay = min(maxDelay, baseDelay * 2^attempt + random_jitter)


Naive retry strategies fail under load:

Immediate retry:

  • All failures retry at once
  • Fails service under load (recovery takes longer)
  • Leads to cascade failure

Fixed backoff (e.g., 1 second always):

  • No pressure reduction during recovery
  • Multiple clients cause thundering herd
  • Predictable = synchronized retries

Exponential backoff:

  • Gives failing service time to recover
  • Each retry waits progressively longer
  • Without jitter, synchronized retries still hammer service

Exponential backoff + jitter:

  • Spreads retry attempts over time
  • Failures de-correlate across clients
  • Service recovery time properly utilized
  • Success likelihood increases with each retry

Real-world example: 100 clients fail simultaneously

  • Immediate retry: 100 requests in milliseconds → failure
  • Fixed backoff: 100 requests at exactly 1s → failure
  • Exponential: 100 requests at 100ms, 200ms, 400ms, 800ms → recovery → success