fabric-error-handlinglisted

# Error handling convention (Fabric notebooks) Two tiers. Pick the right one per block of code; don't mix them inside a single logical operation. ## Tier 1 — Setup / preconditions (hard fail) Raise immediately. No try/except wrapping, no "best effort" semantics. Applies to: - Auth: token acquisition, Key Vault secret fetches, connection-string pulls - Required-config validation: missing required variables, unset placeholders that would produce invalid requests - Target resolution where the target is a single item: resolve a workspace ID, resolve an item ID, lookup the Variable Library GUID Tier 1 functions surface the cause in the exception message (HTTP status, what was missing, what was searched). They never swallow errors to keep the notebook running — if a precondition fails, subsequent cells will produce misleading output or worse, silent data corruption. ## Tier 2 — Bulk operations (soft fail) Track per-item results, continue the loop, print a summary at the end. Applies to: - Per-table maintenance (OPTIMIZE, VACUUM, TBLPROPERTIES alterations) - Per-item enumeration (list all items, extract GUIDs, update a set of value sets) - Per-workspace iteration Canonical result shape — use this exact structure in every Tier 2 notebook: ```python results = { "succeeded": [], # list[str] of item names "skipped": [], # list[dict]: {"name": str, "reason": str} "failed": [], # list[dict]: {"name": str, "error": str} } ``` Append into `succeeded` / `ski