docs: add specification for the error catalogue in the SDK

[ogenstad]

Specification only — no behaviour change. Adds dev/specs/ifc-3034-error-catalogue/ covering how the SDK consumes Infrahub's GraphQL error catalogue, so that ordinary operations raise the specific error for the failure. GraphQLError remains the fallback for failures the catalogue does not cover and stays the common base class, so existing except GraphQLError code keeps working.

Ref: IFC-3034. Related: IFC-2279 (spike), INFP-468 (backend catalogue), GitHub #7498 (out of scope).

Decisions settled while drafting

• A new ApiError base above both AuthenticationError and GraphQLError. Authentication failures reach consumers from the REST path as well as GraphQL, so they cannot simply be re-rooted under GraphQLError. Verified that a 401/403 on a GraphQL call is already handled as an httpx.HTTPStatusError and raises AuthenticationError before the body is parsed for GraphQL errors — so except GraphQLError never caught auth failures, and no dual inheritance is needed to preserve compatibility.
• .code is a catalogue string or None. The /api/... envelope's extensions.code is an integer mirroring the HTTP status, a different thing with a different type; it is not surfaced through .code. The catalogue is GraphQL-only today.
• Generated classes derive their parent from the declared HTTP status — 401/403 under the authentication branch, everything else under GraphQLError — rather than a hand-maintained per-code mapping.
• Infrahub generates the bindings into this repo as its python_sdk submodule, matching how protocols.py and the generated schema models already arrive. No copy of the catalogue schema is vendored here, so there is one freshness invariant instead of two, policed by extending Infrahub's existing validate-generated check. No release-time gate is added on either side.
• Query text is dropped from the message for catalogued errors only; uncatalogued errors keep today's message verbatim.
• NodeNotFoundError, BranchNotFoundError and SchemaNotFoundError are unified with their catalogue counterparts and re-rooted under GraphQLError, accepting that except GraphQLError now also catches client-side lookup misses.

Findings from the code survey worth a reviewer's eye

These are in the spec's Edge Cases section as specific hazards, not hypotheticals:

• An ordered isinstance ladder gets shadowed. infrahub_sdk/ctl/utils.py:58-72 tests GraphQLError at line 67 before (SchemaNotFoundError, NodeNotFoundError, ...) at line 70. Re-rooting those classes makes the later branch unreachable, silently changing CLI output for exactly the errors this feature makes specific. FR-018 requires the correction.
• A renderer with no server errors to render. That same GraphQLError branch renders exc.errors, a list of server error dicts. A unified NodeNotFoundError raised purely client-side has no server response behind it, so the list is empty.
• identifier carries two types. The existing client-side NodeNotFoundError has identifier as a mapping of filters; the catalogue payload has it as a single string. FR-016 mandates the unification; the reconciliation mechanism is left to the plan.
• Eight more, including NodeInvalidError silently inheriting the re-rooting, a pre-existing call site passing a string where GraphQLError expects a list of error dicts, UNDEFINED_ERROR being a real code rather than the absence of one, and GraphQL data errors arriving as HTTP 200 while auth failures arrive as real 401/403 on a separate code path.

Scope

Six prioritised user stories, 28 functional requirements. FR-025 to FR-027 land in the Infrahub repository (generation plus the extended drift check) and are tagged as such; everything else lands here.

Checks

rumdl clean across 131 files; Vale flags nothing in the new files. Requirements checklist at dev/specs/ifc-3034-error-catalogue/checklists/requirements.md passes 16/16 with no [NEEDS CLARIFICATION] markers remaining.

---

Summary by cubic

Documents how the SDK consumes Infrahub’s GraphQL error catalogue so ordinary operations raise specific, typed errors. Documentation only; no behavior change.

• Introduces ApiError above AuthenticationError and GraphQLError to unify server-reported failures across transports.
• .code is a catalogue string or None; the REST integer code is never surfaced as .code.
• Derives generated exception parents from declared HTTP status (401/403 under authentication; others under GraphQLError).
• Infrahub generates bindings into this repo’s submodule; no vendored schema; the validate-generated check enforces freshness.
• Drops query text from messages for catalogued errors only; uncatalogued errors keep today’s message.
• Unifies NodeNotFoundError, BranchNotFoundError, and SchemaNotFoundError with catalogue counterparts under GraphQLError.
• Defines multi-error precedence: the first error in the response determines the raised class; the full list is retained.
• Pins the unified NodeNotFoundError identifier contract: existing construction shapes keep working; server-reported kind and identifier are accessible; one accessor works across cases; any type widening is documented.

Reviewer focus

• Compatibility: ordered isinstance ladders may be shadowed by re-rooting; adjust to preserve existing catches.
• Transport split: catalogue is GraphQL-only; REST keeps its legacy envelope and surfaces no catalogue code.
• Cross-version behavior: unknown codes or fields fall back without parse failures; behavior against pre-catalogue servers is preserved.
• Ownership: FR-025–FR-027 land in the Infrahub repo (generation and validation); all other requirements land here.
• Linked issue: IFC-3034 requirements map to the spec’s functional requirements and success criteria.

^{Written for commit a2d6dcf. Summary will update on new commits.}

[cloudflare-workers-and-pages]

Deploying infrahub-sdk-python with    Cloudflare Pages

Latest commit:	a2d6dcf
Status:	✅  Deploy successful!
Preview URL:	https://86fce214.infrahub-sdk-python.pages.dev
Branch Preview URL:	https://pog-error-catalogue-ifc-3034.infrahub-sdk-python.pages.dev

View logs

[cubic-dev-ai]

All reported issues were addressed across 2 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>