Skip to content

refactor(api,mcp,agent)!: give every product error a stable code - #294

Merged
vishr merged 1 commit into
mainfrom
refactor/error-codes
Oct 9, 2026
Merged

vishr merged 1 commit into
mainfrom
refactor/error-codes

Conversation

@vishr

@vishr vishr commented Oct 9, 2026

Copy link
Copy Markdown
Member

What changed

Every product error a client receives now has a stable, machine-readable snake_case code and a client-safe message. Clients branch on the code instead of message text. This closes the last gap with the shared API conventions in AGENTS.md.

  • HTTP API. One Echo error handler covers handler errors and the router's 404 and 405. It returns exactly {"code", "message"}, plus problems for an invalid spec.
    • Codes default from the status: bad_request, unauthorized, forbidden, not_found, method_not_allowed, conflict, payload_too_large, unsupported_media_type, unprocessable, rate_limited, internal, bad_gateway, unavailable and timeout.
    • Handlers keep their own client-safe messages. An unexpected error gets a generic message, and its text goes only to the log, with the route template.
    • Every error response sets Cache-Control: no-store. HEAD responses carry no body.
  • Specific codes, only where a client branches on the condition: already_current, dashboard_version_not_found, dashboard_version_conflict, invalid_spec and last_active_administrator. The ad hoc error_code field is gone.
  • MCP and agent tool failures carry error: {code, message}, with tool_failed, answer_only and interrupted. A failure keeps structuredContent only when the tool supplied it, so each tool's declared output schema still holds for clients that validate it.
  • Unchanged: OAuth, MCP JSON-RPC, AG-UI, OTLP and /healthz, /readyz and /metrics keep their own error bodies. Panel results keep their status and error fields.
  • UI: ApiError carries code. Missing dashboards and versions, spec advice, timeouts, answer-only refusals, interruptions and version conflicts are all detected by code.
  • Docs: the error contract is documented in AGENTS.md and the HTTP route reference.

Contract changes (breaking, no aliases):

  • API error bodies gain code, and error_code is removed.
  • Tool error payloads change from "error": "<text>" to "error": {"code", "message"}.

Verification

  • just check
  • just test-race when auth, API, ingest, query, MCP, or agent paths changed
  • User-facing behavior and configuration docs are current
  • No credentials, private telemetry, host details, or enterprise-only source are included
  • API, migration, ingest, MCP/AG-UI, or release-contract changes are called out

An independent review found that failed tool calls returned structured content outside the tools' output schemas. It also found two vacuous test assertions, partial error objects being wrapped twice, and the grid detecting conflicts by status. All are fixed here, with tests.

API errors now share one shape, {"code", "message"}, and tool errors one
nested form, error: {code, message}. Clients branch on the code instead of
message text, which closes the last gap with the shared API conventions.

- One Echo error handler covers handler errors and router 404/405. It
  derives a snake_case code from the status, keeps handlers' own
  client-safe messages, returns a generic message for unexpected errors
  and logs them with the route template, sets Cache-Control: no-store, and
  sends no body for HEAD.
- Specific codes exist only where a client branches on the condition:
  already_current, dashboard_version_not_found, dashboard_version_conflict,
  invalid_spec (which keeps problems) and last_active_administrator.
  error_code is gone.
- MCP and agent tool failures carry error: {code, message}, with
  tool_failed, answer_only and interrupted. A failure keeps structured
  content only when the tool supplied it, so tools' output schemas still
  hold for validating clients.
- OAuth, MCP JSON-RPC, AG-UI, OTLP and the operational routes keep their
  own error bodies. Panel results keep their status and error fields.
- The UI's ApiError carries code, and the dashboard grid detects a
  version conflict by code.
- AGENTS.md and the HTTP route reference document the contract.

BREAKING CHANGE: API error bodies gain code and lose error_code; tool
error payloads change from error strings to error objects.
@vishr
vishr merged commit e77dfcf into main Oct 9, 2026
13 checks passed
@vishr
vishr deleted the refactor/error-codes branch October 9, 2026 23:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant