Skip to content

refactor(error): unify structured error handling#3379

Draft
qin-ctx wants to merge 1 commit into
mainfrom
refactor/unify-error-handling
Draft

refactor(error): unify structured error handling#3379
qin-ctx wants to merge 1 commit into
mainfrom
refactor/unify-error-handling

Conversation

@qin-ctx

@qin-ctx qin-ctx commented Jul 20, 2026

Copy link
Copy Markdown
Collaborator

Description

Unify OpenViking API, SDK, and CLI error handling around the structured code, message, and optional details contract. Remove CLI/server message-text classification, preserve unknown upstream messages, and fix structured JSON output for CLI runtime errors.

Human Involvement

  • A human participated in the implementation or review loop
  • This PR was generated entirely by AI agents without human participation in the loop

Related Issue

N/A

Type of Change

  • Bug fix (non-breaking change that fixes an issue)
  • New feature (non-breaking change that adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation update
  • Refactoring (no functional changes)
  • Performance improvement
  • Test update

Changes Made

  • Add canonical server error codes and exception types, with HTTP mapping at the API boundary.
  • Classify known source failures from exception types, status codes, and provider codes; preserve unknown messages instead of parsing their text.
  • Remove the CLI error classifier, keep server messages/details intact in SDK and CLI output, and honor --output json for runtime errors.
  • Map lock/CAS contention to ABORTED, existing resources to ALREADY_EXISTS, invalid URIs to INVALID_ARGUMENT, and invalid state to FAILED_PRECONDITION.
  • Add English/Chinese error-code references plus before/after API and CLI examples.

Testing

  • I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes
  • I have tested this on the following platforms:
    • Linux
    • macOS
    • Windows

Validated locally:

  • cargo test -q -p ov_cli — 403 passed.
  • Focused Python SDK, Feishu, server mapping, path-lock, and compatibility tests — 93 passed.
  • Ruff, rustfmt, and git diff --check passed for the changed error-handling paths.

The broader Python selection is currently blocked by missing watch_manager fixtures and required OpenViking config isolation on the latest main; these failures also affect tests outside this change. The PR is intentionally opened as draft.

Checklist

  • My code follows the project's coding style
  • I have performed a self-review of my code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • Any dependent changes have been merged and published

Screenshots (if applicable)

N/A

Additional Notes

This changes outbound public error codes. Deprecated codes such as CONFLICT, INVALID_URI, NOT_INITIALIZED, and SESSION_EXPIRED remain accepted by compatibility clients, but new server responses use the broader canonical codes documented in docs/en/api/12-error-codes.md and docs/zh/api/12-error-codes.md.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Backlog

Development

Successfully merging this pull request may close these issues.

1 participant