Errors & Retries

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

# 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

1. Identify the error handling API you need (e.g., catchTag, retry)
2. Search docs/​effect-source/​effect/​src/​Effect.ts for the implementation
3. Study the types and error recovery patterns
4. Look at test files for usage examples
5. 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