Errors & Retries

When to use

You’re defining domain errors and recovery policies
You need to map infrastructure errors to domain boundaries
You must add retries, backoff, jitter, and timeouts

Model Errors

import { Data } from "effect"

class ValidationError extends Data.TaggedError("ValidationError")<{ field: string; reason: string }>{}
class NotFoundError extends Data.TaggedError("NotFoundError")<{ id: string }>{}

Map/Boundary

const repoCall = Effect.fail(new ValidationError({ field: "name", reason: "empty" }))

const service = repoCall.pipe(
  Effect.mapError((e) => new ServiceError({ cause: e }))
)

Recover Precisely

program.pipe(
  Effect.catchTags({
    ValidationError: (e) => Effect.succeed(fix(e)),
    NotFoundError: (e) => Effect.succeed(defaultValue)
  })
)

Retry Policies

import { Schedule } from "effect"

const retry = Schedule.exponential("100 millis").pipe(
  Schedule.jittered,
  Schedule.compose(Schedule.recurs(5))
)

const resilient = program.pipe(Effect.retry(retry))

Timeouts & Races

const withTimeout = Effect.timeout(program, "2 seconds")

Guidance & Pitfalls

Create separate TaggedError types per failure mode; avoid generic Error
Map low-level (HTTP/DB) errors to domain errors at the boundary
Retry only transient errors (use predicates with Schedule.whileInput)
Always combine retry with timeouts for bounded latency
Prefer catchTags over broad catchAll for clarity and safety

Real-world snippet: Map HTTP errors and retry selectively

// Verify URL with HEAD-range request, map ResponseError to domain errors,
// retry with exponential backoff unless invalid.
const verify = http.get(url, { headers: { range: "bytes=0-0" } }).pipe(
  Effect.flatMap(HttpClientResponse.filterStatus((s) => s < 400)),
  Effect.catchIf(
    (e) => e._tag === "ResponseError",
    (cause) =>
      cause.response.status < 500
        ? Effect.fail(new VideoInvalidError({ cause: "NotFound" }))
        : Effect.fail(new ExternalLoomError({ cause: cause.response }))
  ),
  Effect.retry({
    schedule: Schedule.exponential("200 millis"),
    times: 3,
    while: (e) => e._tag !== "VideoInvalidError"
  }),
  Effect.catchTag("RequestError", Effect.die)
)

Real-world snippet: Capture structured errors from Cause

import { Cause } from "effect"

const captureErrors = (cause: Cause.Cause<unknown>) => Effect.gen(function* () {
  if (Cause.isInterruptedOnly(cause)) return { interrupted: true, errors: [] }
  const raw = captureErrorsFrom(cause)
  const errors = yield* Effect.forEach(raw, transformRawError({ stripCwd: true }))
  return { interrupted: false, errors }
})

Quick Heuristics

Domain errors → TaggedError per type
Map low-level to high-level at boundaries
Retry only transient errors; predicate with Schedule.whileInput

Cross-links

Foundations: operator selection and .pipe style
Concurrency: race and timeout patterns
EffectPatterns inspiration: https://github.com/PaulJPhilp/EffectPatterns

Local Source Reference

CRITICAL: Search local Effect source before implementing

The full Effect source code is available at docs/effect-source/. Always search the actual implementation before writing Effect code.

Key Source Files

Effect: docs/effect-source/effect/src/Effect.ts
Data: docs/effect-source/effect/src/Data.ts
Schedule: docs/effect-source/effect/src/Schedule.ts
Cause: docs/effect-source/effect/src/Cause.ts

Example Searches

bash

# Find error handling patterns
grep -F "catchTag" docs/effect-source/effect/src/Effect.ts
grep -F "catchAll" docs/effect-source/effect/src/Effect.ts
grep -F "mapError" docs/effect-source/effect/src/Effect.ts

# Study TaggedError
grep -F "TaggedError" docs/effect-source/effect/src/Data.ts

# Find retry and schedule patterns
grep -F "retry" docs/effect-source/effect/src/Schedule.ts
grep -F "exponential" docs/effect-source/effect/src/Schedule.ts
grep -F "jittered" docs/effect-source/effect/src/Schedule.ts

# Study Cause operations
grep -F "isInterruptedOnly" docs/effect-source/effect/src/Cause.ts

Workflow

Identify the error handling API you need (e.g., catchTag, retry)
Search docs/effect-source/effect/src/Effect.ts for the implementation
Study the types and error recovery patterns
Look at test files for usage examples
Write your code based on real implementations

Real source code > documentation > assumptions

References

Agent Skills overview: https://www.anthropic.com/news/skills
Skills guide: https://docs.claude.com/en/docs/claude-code/skills

Search AI Tools

effect-errors-retries

Install this agent skill to your Project

SKILL.md