Skip to content

Conversation

@iffy
Copy link
Member

@iffy iffy commented Dec 9, 2025

Pull request for structured error codes to address #29. If GitHub doesn't make a nice HTML-viewable diff of the protocol, I'll put one up. The diff to look at is protocol.md. Changes can best be summarized using the AccountSet.

Before this PR:

{
  "errors": ["You must reauthenticate."],
  "accounts": [
    {
      "org": {
        "domain": "mybank.com",
        "sfin-url": "https://sfin.mybank.com"
      },
      "id": "2930002",
      "name": "Savings",
      "currency": "USD",
      "balance": "100.23",
      "available-balance": "75.23",
      "balance-date": 978366153,
      "transactions": []
    }
  ]
}

With this PR:

{
  "errlist": [
    {
      "code": "con.auth",
      "message": "Authentication required",
      "conn_id": "CON-10829309823094234",
    }
  ],
  "connections": [
    {
      "conn_id": "CON-10829309823094234",
      "name": "My Bank - Jeff",
      "org_id": "INST-982394823948230-2340923094",
      "org_name": "My Bank",
      "org_url": "https://mybank.com",
      "sfin_url": "https://sfin.mybank.com",
    }
  ],
  "accounts": [
    {
      "id": "2930002",
      "name": "Savings",
      "conn_id": "CON-10829309823094234",
      "currency": "USD",
      "balance": "100.23",
      "available-balance": "75.23",
      "balance-date": 978366153,
      "transactions": []
    }
  ]
}

During a migration period between the two versions, servers can provide both simultaneously like this:

{
  "errlist": [
    {
      "code": "con.auth",
      "message": "Authentication required",
      "conn_id": "CON-10829309823094234",
    }
  ],
  "errors": ["Authentication required"],
  "connections": [
    {
      "conn_id": "CON-10829309823094234",
      "name": "My Bank - Jeff",
      "org_id": "INST-982394823948230-2340923094",
      "org_name": "My Bank",
      "org_url": "https://mybank.com",
      "sfin_url": "https://sfin.mybank.com",
    }
  ],
  "accounts": [
    {
      "org": {
        "domain": "mybank.com",
        "sfin-url": "https://sfin.mybank.com"
      },
      "id": "2930002",
      "name": "Savings",
      "conn_id": "CON-10829309823094234",
      "currency": "USD",
      "balance": "100.23",
      "available-balance": "75.23",
      "balance-date": 978366153,
      "transactions": []
    }
  ]
}

Perhaps we should be allowed to specify a minimum version when making a request to test that things won't break for us when the old stuff is eventually removed? Something like ?min-version=2

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants