Errors

Errors

• Exception Hierarchy
  • SDK hierarchy (singer_sdk.exceptions)
  • Singer-protocol hierarchy (singer_sdk.singerlib.exceptions)
  • Exception groups
    • ConfigurationError
    • DiscoveryError
    • MappingError
    • SyncError — base for runtime errors
      • Fatal (FatalSyncError)
      • Retriable (RetriableSyncError)
      • Ignorable (IgnorableSyncError)
      • Data quality (DataError)
    • SyncLifecycleSignal
  • Catching SDK exceptions broadly
  • Choosing the right exception
• Exception Hierarchy — Design
  • 1. Pre-Phase-1 State
    • 1.1 Flat hierarchy
    • 1.2 Naming inconsistency
    • 1.3 Exceptions scattered across files
    • 1.4 No recovery semantics encoded in the type
  • 2. Design Principles
    • 2.1 Encode intent in the type
    • 2.2 Group by domain phase and recovery strategy
    • 2.3 Consistent Error suffix (PEP 8)
    • 2.4 Single source of truth
    • 2.5 Only handle what you can act on
  • 3. Implemented Hierarchy
    • 3.1 Annotated tree (Phases 1 + 2)
    • 3.2 Singer-protocol hierarchy (singerlib — intentionally separate)
    • 3.3 Phase 3+ migration candidates
  • 4. Recovery Strategy Table
  • 5. IgnorableAPIError Specification (closes #1689)
    • 5.1 Motivation
    • 5.2 Class definition
    • 5.3 Catch site
    • 5.4 Interaction with backoff
  • 6. Migration / Backward Compatibility
    • 6.1 Additive insertion pattern
    • 6.2 What changes for SDK users
  • 7. Implementation Roadmap
    • PR 1 — Hierarchy scaffold ✅ Complete
    • PR 2 — Consolidate scattered exceptions ✅ Complete
    • PR 3 — IgnorableAPIError handling in REST stream
    • PR 4 — Wire lifecycle signals, fatal handlers, and per-stream outcomes
    • PR 5 — Docs, changelog, deprecations
  • 8. Per-Stream Sync Outcomes
    • 8.1 SyncResult enum
    • 8.2 How outcomes are set
    • 8.3 Child stream outcome propagation
    • 8.4 Tap-level exit code
    • 8.5 Log summary
    • 8.6 Relationship to the exception hierarchy
  • 9. Verification