Files
actual/upcoming-release-notes/stable-api-error-codes.md
a862d463d7 [AI] api: attach stable error codes that survive the worker boundary (#8437)
* [AI] Attach stable error codes that survive the worker boundary

Rejections from the backend worker reached consumers as an English
message only: the machine-readable reason was stripped when the error
was serialized for postMessage, so API consumers had to regex the prose
to categorize failures.

- Serialize rejected handler errors through a shared helper that lifts
  the reason slug onto a `code` field (plus `name`) on the envelope, so
  it survives the worker/utility-process boundary. `message` is
  unchanged, so the change is purely additive.
- Tag the common connect failures with codes at their throw sites:
  init auth failures (network-failure, invalid-password, token-expired)
  and api/download-budget, api/load-budget, api/sync, api/bank-sync
  (budget-not-found, missing-key, decrypt-failure, ...).
- Harden the error post: if the original error holds a non-cloneable
  value (e.g. an Emscripten ErrnoError carrying methods), postMessage
  used to throw a DataCloneError in the worker and that clone failure
  replaced the real error. Retry with a plain cloneable shape instead.
- Add an integration test driving the real web client/server connection
  pair across a structured-clone channel, document the codes in the API
  reference, and add a release note.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AG6f77cRxhwPFjsNpQRmYo

* [AI] Remove worker-boundary connection integration test

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AG6f77cRxhwPFjsNpQRmYo

* [AI] Remove prose comment from connection error helpers

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AG6f77cRxhwPFjsNpQRmYo

* [AI] Simplify worker-boundary error posting

- Hoist the three-way reply-envelope dispatch out of the two platform
  connection files into a single postErrorReply helper, so the envelope
  rules and the DataCloneError fallback live in one place.
- Return APIError envelopes from coerceError unchanged, and drop the
  unreachable fallbacks and unused meta field from the cloneable shape.
- Let withErrorCode accept an undefined code, removing the one-off
  ternary at the bank-sync throw site.
- Declare the client-side connection error shape once as
  ConnectionError instead of twice inline.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AG6f77cRxhwPFjsNpQRmYo

* [AI] Address review feedback on error-code contract wording and types

- Docs and release note: scope the stable-code promise to the common
  documented failures, and say errors "usually" carry a message.
- ConnectionError: model APIError (message required) and ServerError
  (message may be absent) as separate variants to match the wire shape,
  and adapt the sendCatch consumers in SavedFilterMenuButton.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AG6f77cRxhwPFjsNpQRmYo

---------

Co-authored-by: Claude <noreply@anthropic.com>
2026-07-16 06:08:18 +00:00

185 B

category, authors
category authors
Enhancements
MatissJanis

Common API failures now include a stable code so apps built on the API can show their own clear message for each kind of failure.