Repository navigation
refactor(api,mcp,agent)!: give every product error a stable code - #294
Merged
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
Every product error a client receives now has a stable, machine-readable snake_case
codeand a client-safemessage. Clients branch on the code instead of message text. This closes the last gap with the shared API conventions in AGENTS.md.{"code", "message"}, plusproblemsfor an invalid spec.bad_request,unauthorized,forbidden,not_found,method_not_allowed,conflict,payload_too_large,unsupported_media_type,unprocessable,rate_limited,internal,bad_gateway,unavailableandtimeout.Cache-Control: no-store. HEAD responses carry no body.already_current,dashboard_version_not_found,dashboard_version_conflict,invalid_specandlast_active_administrator. The ad hocerror_codefield is gone.error: {code, message}, withtool_failed,answer_onlyandinterrupted. A failure keepsstructuredContentonly when the tool supplied it, so each tool's declared output schema still holds for clients that validate it./healthz,/readyzand/metricskeep their own error bodies. Panel results keep theirstatusanderrorfields.ApiErrorcarriescode. Missing dashboards and versions, spec advice, timeouts, answer-only refusals, interruptions and version conflicts are all detected by code.Contract changes (breaking, no aliases):
code, anderror_codeis removed."error": "<text>"to"error": {"code", "message"}.Verification
just checkjust test-racewhen auth, API, ingest, query, MCP, or agent paths changedAn 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.