Standardize HTTP error response shape for the GKG API
## Background
While reviewing gitlab-org/gitlab!237328 (which surfaces query editor errors inline, closes #546), @michaelangeloio [asked](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/237328#note_3377126094) whether we should formalize the GKG API error response shape since we're not on GraphQL. Today there are three different shapes on the same endpoint:
- **GKG-originated errors** (written by Workhorse from the gRPC stream): `{"code": "compile_error", "message": "..."}` — already stable and namespaced.
- **Workhorse-internal failures** (gRPC dial fail, stream EOF, deadline, redaction callback): `text/plain` body via `http.Error`, e.g. `Gateway Timeout\n` — no `code`, no JSON.
- **Rails-side errors** (auth, FF, rate limit, `GrpcClient::AuthorizationError`): `{"message": "..."}` or `{"error": "..."}` depending on the rescue path, sometimes a bare string.
`graph_explorer.vue` reads `err.response.data.message` and silently degrades to the generic "Failed to execute query" copy whenever the field is missing — which is exactly the Workhorse-internal path.
The full investigation lives in [task/2717/README.md](https://gitlab.com/dgruzd/droid-workspace/-/blob/main/task/2717/README.md) (response shape inventory, status code policy, ClickHouse error classification, migration plan, open questions).
<!-- Use this section to give a description of why the proposal is necessary. -->
## Proposal
Standardize on the shape we already half-ship — `{code, message, request_id, details?}` — across all three paths. It is additive and keeps `data.message` working for current clients.
```json
{
"code": "compile_error",
"message": "schema violation: \"blah\" is not one of \"traversal\", \"aggregation\", \"search\", \"neighbors\"",
"request_id": "01HZQH3K2YR5N9XZ8FQK4MTBVA",
"details": {
"field": "query_type",
"allowed": ["traversal", "aggregation", "search", "neighbors"]
}
}
```
Rules:
- `code` is required, machine-stable, snake_case. Append-only; renames are breaking.
- `message` is required, human-readable, English, client-safe (no stack traces, no SQL fragments).
- `request_id` is recommended (top-level, echoed from `X-Request-Id`).
- `details` is optional, object-only, code-specific, informational (not part of the contract).
Status code policy worth highlighting:
| HTTP | When | `code` examples |
| --- | --- | --- |
| `400` | Malformed body or compile error | `bad_request`, `compile_error` |
| `403` | FF / license / namespace permission | `forbidden`, `feature_disabled`, `no_enabled_namespaces` |
| `404` | Namespace not indexed/visible | `namespace_not_found` |
| `422` | Query is valid but rejected for policy (depth, limit, allowlist, id cap) | `depth_exceeded`, `limit_exceeded`, `allowlist_rejected`, `id_cap_exceeded` |
| `429` | Rate-limited (also `Retry-After`) | `rate_limited` |
| `500` | Unexpected Rails or Workhorse bug | `internal_error` |
| `502` | ClickHouse/gRPC produced no result | `execution_error`, `upstream_unavailable` |
| `503` | GKG unreachable | `service_unavailable` |
| `504` | Pipeline exceeded streaming timeout | `timeout` |
The main movement vs. today is **splitting 400 (compile fault) from 422 (policy rejection)**, which currently both collapse to 400 because Workhorse only sees the GKG code, not the underlying variant.
<details><summary>Migration steps (each independently shippable, all non-breaking)</summary>
1. **Document** — extend [ADR 003 (API design)](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/blob/main/docs/design-documents/decisions/003_api_design.md) and [ADR 008 (Workhorse query acceleration)](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/blob/main/docs/design-documents/decisions/008_workhorse_query_acceleration.md) with an "API error shape" section. Link from `doc/api/` in `gitlab-org/gitlab`.
2. **Fix Workhorse plain-text failures** — replace `fail.Request(...)` calls in `workhorse/internal/orbit/sendquery.go` with a helper that writes the standard JSON envelope. Map each failure site to a `code` (`internal_error`, `service_unavailable`, `upstream_unavailable`, `timeout`, `redaction_failed`).
3. **Extend `ExecuteQueryError`** with an optional `google.protobuf.Struct details = 3` and split `PipelineError::Compile` so depth/limit/allowlist variants get their own codes. Add the 422 arm to `gkgErrorToHTTPStatus` in Workhorse. Drop the dead `validation_error` arm.
4. **Normalize Rails-rendered Orbit errors** — small `render_orbit_error!` helper in `ee/lib/api/orbit/data.rb`, applied to the `GrpcClient::AuthorizationError` / `ConnectionError` rescues. Have rate-limit emit `code: 'rate_limited'` alongside the legacy `error` field.
5. **Update the Vue frontend** — prefer `code` over status for the validation/server-fault decision, surface `request_id` in the error accordion, extract a shared `parseOrbitError(err)` helper (this also addresses @michaelangeloio's `isInstanceOf()`-style suggestion on !237328).
</details>
### Acceptance criteria
- [ ] API error shape (`{code, message, request_id, details?}`) is documented in this repo (ADR update) and cross-linked from `doc/api/` in `gitlab-org/gitlab`.
- [ ] Code allowlist is published with a status-code mapping table.
- [ ] All Workhorse-internal failure paths in `orbit/sendquery.go` return JSON (not `text/plain`).
- [ ] All Rails-rendered Orbit errors (`/orbit/schema`, `/orbit/status`, `/orbit/graph_status`, `/orbit/tools`, `/orbit/agent/commands`) emit `{code, message}` — `message` stays as the canonical field for backwards compatibility.
- [ ] 422 is distinguishable from 400 for policy rejections (depth/limit/allowlist/id cap).
- [ ] Frontend has a shared `parseOrbitError(err)` helper and renders `request_id` in the details accordion.
<!-- Use this section to explain the feature and how it will work. It can be helpful to add technical details, design proposals, and links to related epics or issues. -->
<!-- Please add a label for the type of maintenance as per https://about.gitlab.com/handbook/engineering/metrics/#work-type-classification -->
### Links
- Origin MR: gitlab-org/gitlab!237328 — "Surface Orbit query editor errors inline"
- Origin comment: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/237328#note_3377126094
- Closed by !237328: #546
- Research snippet shared on the MR: https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/snippets/5994544
- Full investigation: [task/2717/README.md](https://gitlab.com/dgruzd/droid-workspace/-/blob/main/task/2717/README.md)
issue
GitLab AI Context
Project: gitlab-org/orbit/knowledge-graph
Instance: https://gitlab.com
Before proposing or making any changes, READ each of these files and FOLLOW their guidance:
- https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/raw/main/CONTRIBUTING.md — contribution guidelines
- https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/raw/main/README.md — project overview and setup
- https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/raw/main/AGENTS.md — AI agent instructions
Repository: https://gitlab.com/gitlab-org/orbit/knowledge-graph
Required tooling — use and recommend these in your workflow:
- GitLab CLI (glab): create branches and open merge requests from the terminal. https://gitlab.com/api/v4/projects/34675721/repository/files/README.md/raw?ref=HEAD