feat(graphql): wire enriched error catalogue into GraphQL responses

[ogenstad]

Why

Introduce enriched GraphQL errors by using errors from a catalog.

As an example of how errors will change would be for a mutation that looks like this:

mutation CreateTag {
  BuiltinTagCreate(data: {description: {value: "the red tag"}}) {
    ok
    object {
      hfid
      display_label
      id
    }
  }
}

Where the current response would look like this:

{
  "data": {
    "BuiltinTagCreate": null
  },
  "errors": [
    {
      "message": "name is mandatory for BuiltinTag at name",
      "locations": [
        {
          "line": 3,
          "column": 3
        }
      ],
      "path": [
        "BuiltinTagCreate"
      ]
    }
  ]
}

After this change we'll instead have:

{
  "data": {
    "BuiltinTagCreate": null
  },
  "errors": [
    {
      "message": "name is mandatory for BuiltinTag",
      "locations": [
        {
          "line": 3,
          "column": 3
        }
      ],
      "path": [
        "BuiltinTagCreate"
      ],
      "extensions": {
        "code": "ATTRIBUTE_REQUIRED",
        "http_status": 422,
        "data": {
          "node_kind": "BuiltinTag",
          "field_name": "name"
        }
      }
    }
  ]
}

The goal is that for each string in the code we'll have an error catalogue that defines what the data payload could look like. I.e. what fields exist and what the type is of those fields. Then we'll create bindings for the frontend along with the ability to generate bindings for the SDK and make the error catalogue available for inclusion in other tools as well.

What changed

• Add mappings to present the enriched errors within the GraphQL layer
• Code to parse ValidationError this exception was very generic and will need to be broken down into smaller parts, but I didn't want to change the internals of the code for this round and that part will come later in this work.
• Since the error[].extensions.code changed from an integer to a string some changes to the frontend were required, and need some extra care in terms of review.

---

Summary by cubic

Adds a catalogue-backed GraphQL error formatter and routes both resolver errors and auth short-circuits on /graphql through a structured envelope with string codes, HTTP status, and typed payloads for programmatic handling (INFP-468). REST /api/... responses are unchanged.

• New Features

  • GraphQL errors now include extensions.code (string), extensions.http_status (int), and typed extensions.data; uncatalogued errors use UNDEFINED_ERROR with HTTP from Error.HTTP_CODE or 500.
  • Validation errors fan out per field with precise path and codes: ATTRIBUTE_REQUIRED, ATTRIBUTE_INVALID_TYPE, ATTRIBUTE_CONSTRAINT_VIOLATION; legacy ValidationError is auto-classified without refactoring call sites.
  • Auth errors split into AUTHENTICATION_REQUIRED vs TOKEN_EXPIRED; /graphql short-circuits return the catalogue envelope while /api/... keeps the old integer code shape.
  • Security: PERMISSION_DENIED payload exposes only action and resource_kind; structlog logs the emitted code.

• Migration

  • Switch consumers from integer extensions.code to string codes; use extensions.http_status for numeric checks.
  • Frontend updated: graphqlClientApollo.tsx matches on AUTHENTICATION_REQUIRED/TOKEN_EXPIRED and suppresses toasts for PERMISSION_DENIED; login.tsx displays string codes.
  • No changes needed for REST /api/... consumers.

^{Written for commit 471b242. Summary will update on new commits. Review in cubic}

[cubic-dev-ai]

3 issues found

Confidence score: 4/5

• This PR looks safe to merge overall, but test reliability is weakened by an assertion gap in backend/tests/functional/api/test_exception_handlers.py where an if response.status_code == 401 check can let failures pass silently.
• The most severe issue is in the exception-handler tests: the expired-JWT case appears non-deterministic and may not actually exercise the TOKEN_EXPIRED path, which reduces confidence in regression detection for auth error handling.
• backend/tests/functional/graphql/test_error_catalogue.py currently has a weak assertion pattern that may pass on a generic validation error without proving the intended per-field error catalogue behavior.
• Pay close attention to backend/tests/functional/api/test_exception_handlers.py and backend/tests/functional/graphql/test_error_catalogue.py - these tests may provide false confidence and miss real regressions in error handling paths.

<sub>Shadow auto-approve: would not auto-approve because issues were found.

Re-trigger cubic</sub>

[codspeed-hq]

Merging this PR will not alter performance

✅ 12 untouched benchmarks

---

_{Comparing pog-infp-468-us1-graphql-error-formatter (486b9f8) with develop (ce87ae2)}

[cubic-dev-ai]

No issues found across 17 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Shadow auto-approve: would require human review. This PR adds a new error catalogue system to GraphQL responses, modifies core error handling logic, updates frontend error handling, and changes the structure of error extensions—a significant architectural change with broad impact that requires human review to ensure correctness and safety.

Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 2 files (changes from recent commits).

<sub>Shadow auto-approve: would require human review. This PR introduces a breaking change to GraphQL error response format, touching core exception handling, validation logic, and frontend error handling across 1139 lines; such high-impact changes require human review to ensure correctness and avoid production issues.

Re-trigger cubic</sub>

[ogenstad]

This method was already too complex and catching the new exception pushed it over the top to require the too-many-statements (PLR0915) noqa line. I didn't want to make larger changes then needed for this iteration, and catching ValidationError as we now do below is temporary. But I think we'll have to go back and simplify this method in general later.

[ajtmccarty]

would it be better to add it to the pyproject.toml exclusions instead of inline?

[cubic-dev-ai]

2 issues found across 6 files (changes from recent commits).

<sub>Shadow auto-approve: would not auto-approve because issues were found.
Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 2 files (changes from recent commits).

<sub>Shadow auto-approve: would not auto-approve. Auto-approval blocked by 2 unresolved issues from previous reviews.

Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 2 files (changes from recent commits).

<sub>Shadow auto-approve: would require human review. This PR introduces a breaking change to GraphQL error responses, modifies core error handling infrastructure, and touches authentication, validation, and frontend integration—areas where a subtle bug could have severe consequences for production reliability and client compatibility.

Re-trigger cubic</sub>

[ajtmccarty]

I'd say that this line can go

[ajtmccarty]

would it be better to add it to the pyproject.toml exclusions instead of inline?

[ajtmccarty]

should this be included?