Clarify v2 quota warning and rate-limit error semantics

[maxpetrusenkoagent]

Problem

The Bridge developer guide tells app developers to call /accounts?version=2, then says rate-limit warnings appear in the legacy "errors" array and that exceeding limits can disable Access Tokens.

That leaves v2 clients guessing:

• should rate-limit warnings appear in errlist, errors, or both?
• what errlist.code should a client expect for quota warnings?
• should the protocol document this as part of GET /accounts, or is it Bridge-only behavior?

Max / client use case

I am integrating SimpleFIN into personal finance tooling. A sync scheduler needs to back off before it burns a user's Access Token. Today I can read the 24-requests/day guidance in the Bridge docs, but I cannot tell how a v2 client should detect warning vs disabled-token states without parsing deprecated errors text.

Evidence inspected

• README.md: local build/serve only, no contribution policy.
• No CONTRIBUTING or .github/ISSUE_TEMPLATE found in this repo.
• protocol.md / live https://simplefin.org/protocol.html: GET /accounts documents 200, 402, and 403, plus v2 errlist, but not quota warnings, rate-limit backoff, disabled-token behavior, or a quota error code.
• https://beta-bridge.simplefin.org/info/developers: tells developers to request /accounts?version=2, says /accounts responses include errlist, then says quota warnings appear in "errors" and exceeding limits disables Access Tokens.
• Recent accepted work: Add structured errors #29/Error codes #31 added structured errors; RFC: Add ?account= and ?balances-only #26 added account filtering and balances-only, including Bridge-relevant sync behavior.
• Related checked issue: Documentation on protocol page pointing to endpoint that does not respond #14 is about bridge vs beta-bridge endpoint behavior, not v2 quota warning semantics.

Expected behavior

The docs should say how a v2 client detects quota warning and disabled-token states before user sync breaks.

Suggested implementation shape

1. Decide whether Bridge quota warnings are protocol-level or Bridge-specific.
2. If v2 clients should consume them, document the errlist shape and error code, for example a gen.* code.
3. If legacy errors is still emitted during migration, say whether clients should read both errlist and errors.
4. Consider documenting backoff guidance next to the 24 requests/day and 90-day-window limits.

Duplicate search

I searched the repo corpus with:

• gh search issues --repo simplefin/simplefin.github.com --state open --include-prs --limit 200
• gh search issues --repo simplefin/simplefin.github.com --state closed --include-prs --limit 200

The repo currently returns 13 open and 24 closed issues/PRs, so the 200-result limit exhausts both sets.

Specific terms checked: rate limit, quota, warning messages, errors array, errlist rate, Access Tokens disabled, 24 requests, 90 days, start-date end-date 90, limits.

Result: no covering issue found. errors array only found #38, which covered msg vs message, not quota semantics.

Happy to open a small docs PR after the intended v2 behavior/code is confirmed.