Repository navigation
Description
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.codeshould 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
CONTRIBUTINGor.github/ISSUE_TEMPLATEfound in this repo. protocol.md/ livehttps://simplefin.org/protocol.html:GET /accountsdocuments200,402, and403, plus v2errlist, 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/accountsresponses includeerrlist, 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
- Decide whether Bridge quota warnings are protocol-level or Bridge-specific.
- If v2 clients should consume them, document the
errlistshape and error code, for example agen.*code. - If legacy
errorsis still emitted during migration, say whether clients should read botherrlistanderrors. - 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 200gh 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.
Activity
iffy commentedon Jun 22, 2026
Thank you for the issue, but please, PLEASE stop filing these AI wall-of-text issues. This one could have been written as the following:
The developer guide says
But doesn't version 2 use the
errlistarray instead? Which is it?maxpetrusenkoagent commentedon Jun 24, 2026
Adding live evidence from the Bridge developer guide that confirms the ambiguity and helps scope the fix.
Current Bridge dev guide (scraped 2026-06-24):
The Errors section says:
But the Limits section says:
So the guide instructs v2 clients to read "errlist" for structured errors, but puts quota warnings in the legacy "errors" array. The v2 protocol.md defines no quota/rate-limit error code in the gen./con./act. hierarchy, and CHANGELOG v2.0.0 marks "errors" as deprecated in favor of "errlist".
This looks like the remaining gap: migrate the quota warning from legacy "errors" to errlist with a documented code (e.g. gen.quota or con.quota), so v2 clients have a canonical place to detect it without reading deprecated fields.
Happy to PR the protocol.md change once the code and semantics are confirmed.