Handle usage API business errors

[KiwiGaze]

Summary

• validate HTTP JSON responses for top-level GLM business failures
• preserve business codes and server messages in structured diagnostics
• map documented authentication business codes to auth-error
• keep usable primary usage or balance data when supplementary requests fail

Root cause

The usage clients treated HTTP status as the only success signal. GLM endpoints can return HTTP 200 with a failed business envelope, causing authentication and server failures to be interpreted as empty successful data.

User impact

Usage status now reports authentication, network, and server failures accurately instead of incorrectly displaying no-data. Authentication failures also expose the existing API-key recovery action.

Validation

• pnpm test — 108 tests passed
• pnpm typecheck
• pnpm lint
• git diff --check

Closes #29

Summary by CodeRabbit

• Bug Fixes
  • Improved usage/balance error reporting for GLM responses delivered with HTTP 200.
  • Authentication and server failures are no longer downgraded to “no data,” and business error codes/messages are preserved in logs.
  • Authentication failures consistently trigger the API-key recovery action.
  • Enhanced handling for cancellation, malformed business envelopes, and supplementary (token-packages) request degradation.
• Documentation
  • Updated changelog with notes about the improved usage error reporting.
• Tests
  • Expanded coverage for business-envelope shapes and classification behavior.

[coderabbitai]

Important

Review skipped

No new commits to review since the last review.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 18daa8ea-6cd2-4ec7-8f47-213e088b2d56

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

HTTP 200 GLM responses are now validated for business-level failures. Usage requests preserve authentication, server, parse, and cancellation errors, apply primary-versus-supplementary failure handling, and retain business codes and server messages in diagnostics.

Changes

Usage Error Reporting

Layer / File(s)	Summary
Business response parsing and error contracts src/client/errors.ts, src/client/response.ts, src/client/response.test.ts	Business envelopes, invalid JSON, authentication codes, diagnostics, and cancellation behavior are classified and tested.
Usage request routing and error mapping src/client/usage.ts, src/client/usage.test.ts	Quota, subscription, account, and token-package requests use shared parsing with primary/supplementary failure handling, structured logging, and regression coverage.
Usage error reporting release note CHANGELOG.md	The unreleased changelog records business-error classification, preserved diagnostics, and API-key recovery behavior.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant UsageClient
  participant readBusinessJson
  participant ErrorMapping
  participant logger
  UsageClient->>readBusinessJson: Request usage endpoint
  readBusinessJson->>ErrorMapping: Classify HTTP or business response
  ErrorMapping-->>UsageClient: Return snapshot or mapped error state
  UsageClient->>logger: Log supplementary request failure

Loading

Possibly related PRs

• KiwiGaze/glm-for-copilot#17: Modifies the same usage client and snapshot/error mapping tests.
• KiwiGaze/glm-for-copilot#26: Modifies overlapping usage-client and regional authentication paths.
• KiwiGaze/glm-for-copilot#28: Modifies overlapping Standard API balance and business-code handling paths.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and clearly summarizes the main change: handling usage API business errors.
Linked Issues check	✅ Passed	The changes detect HTTP 200 business failures, map auth codes to auth-error, preserve messages, avoid no-data, and add regression tests for both endpoints.
Out of Scope Changes check	✅ Passed	The modified files stay focused on business-error handling, diagnostics, and regression coverage with no clear unrelated feature work.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/usage-business-errors

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/client/response.ts`:
- Around line 56-63: Update the response parsing around errorValue, errorObject,
code, and message so nested error.code and errorObject.message take precedence
whenever error is present, while retaining top-level values as fallbacks. Add a
regression test covering a mixed envelope with top-level code 200 and nested
invalid-token error details, verifying the nested code and message drive
failure/auth classification.

In `@src/client/usage.ts`:
- Around line 145-163: Update the hasAccountData calculation in the usage
aggregation flow to treat every account-report field, including spent, gifted,
and frozen balances, as usable primary data. Ensure a rejected package request
degrades to the account snapshot rather than returning an error when any one of
these fields is present. Add coverage for each previously omitted field with a
failed package request.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4dcd0695-e258-48f3-abaa-0d1117a0dd52

📥 Commits

Reviewing files that changed from the base of the PR and between 1e051f0 and d5830a4.

📒 Files selected for processing (6)

• CHANGELOG.md
• src/client/errors.ts
• src/client/response.test.ts
• src/client/response.ts
• src/client/usage.test.ts
• src/client/usage.ts

[KiwiGaze]

@codex @coderabbitai review

[coderabbitai]

@KiwiGaze: Starting a review of the changes in #31.

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 🚀

Reviewed commit: 1c787f7f0b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".