Skip to content

April 5: MAST Exceptions and README Wayfinding

Part 2 of the exception infrastructure split — MAST exception subtypes landed — plus a small README update that actually matters for people finding the architecture docs.

Developer Journal

MAST exception subtypes (PR 2 of 2)

Yesterday's exception hierarchy work shipped the backbone; today's PR layered the MAST-specific subtypes on top and narrowed the catches in the MAST service and MAST controller.

  • MastUnavailableException — upstream 5xx or timeout, maps to 503 with retry-after
  • MastProductNotFoundException — upstream 404, maps to 404 with product URI
  • MastAuthenticationException — credential expiry or token refusal
  • MastRateLimitException — 429 from MAST, preserves their retry-after header

Narrowed catch (Exception) to catch (MastException) in the places that were already doing MAST-aware handling. The generic middleware from yesterday's PR catches anything that leaks through, so there's no behavioral regression if a new code path raises something unexpected — just a less specific error message.

Tracking issue for further MAST exception narrowing is open as a tech-debt item. The bulk of the low-hanging cases are done.

Trivial but surprisingly overdue — the README had no link to docs/architecture/. Anyone landing on the repo had to dig through mkdocs or grep the docs tree to find the 4+1 views from March 31. Added the link with a one-line description under the "where to go next" section.

What shipped

PR Title
#1014 docs: add architecture documentation link to README
#1013 feat: add MAST exception subtypes and narrow MAST layer catches (PR 2 of 2)