{"record":{"id":"9ae0e00999fba9c1","repo":"we-promise/sure","slug":"payment-required","errorCode":"payment_required","errorMessage":"Payment required to access this account","messagePattern":"Payment required to access this account","errorType":"exception","errorClass":"Provider::Simplefin::SimplefinError","httpStatus":402,"severity":"error","filePath":"app/models/provider/simplefin.rb","lineNumber":94,"sourceCode":"    accounts_url += \"?#{URI.encode_www_form(query_params)}\" unless query_params.empty?\n\n    # The access URL already contains HTTP Basic Auth credentials\n    # Use retry logic with exponential backoff for transient network failures\n    # Use self.class.get to inherit class-level SSL and timeout defaults\n    response = with_retries(\"GET /accounts\") do\n      self.class.get(accounts_url)\n    end\n\n    case response.code\n    when 200\n      JSON.parse(response.body, symbolize_names: true)\n    when 400\n      Rails.logger.error \"SimpleFin API: Bad request - #{response.body}\"\n      raise SimplefinError.new(\"Bad request to SimpleFin API: #{response.body}\", :bad_request)\n    when 403\n      raise SimplefinError.new(\"Access URL is no longer valid\", :access_forbidden)\n    when 402\n      raise SimplefinError.new(\"Payment required to access this account\", :payment_required)\n    when 429\n      Rails.logger.warn \"SimpleFin API: Rate limited - #{response.body}\"\n      raise SimplefinError.new(\"SimpleFin rate limit exceeded. Please try again later.\", :rate_limited)\n    when 500..599\n      Rails.logger.error \"SimpleFin API: Server error - Code: #{response.code}, Body: #{response.body}\"\n      raise SimplefinError.new(\"SimpleFin server error (#{response.code}). Please try again later.\", :server_error)\n    else\n      Rails.logger.error \"SimpleFin API: Unexpected response - Code: #{response.code}, Body: #{response.body}\"\n      raise SimplefinError.new(\"Failed to fetch accounts: #{response.code} #{response.message} - #{response.body}\", :fetch_failed)\n    end\n  end\n\n  def get_info(base_url)\n    # Use self.class.get to inherit class-level SSL and timeout defaults\n    response = self.class.get(\"#{base_url}/info\")\n\n    case response.code\n    when 200","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/we-promise/sure/blob/e69894adb92547273377398c15f45c979cd9416a/app/models/provider/simplefin.rb#L76-L112","documentation":"Raised by Provider::Simplefin#get_accounts when the accounts endpoint returns 402 Payment Required, with error_type :payment_required. SimpleFin bridges use 402 when the account/bridge requires payment — typically a lapsed bridge subscription or an institution tier not covered by the user's plan.","triggerScenarios":"Calling get_accounts after the user's SimpleFin bridge subscription expired or the linked institution moved to a paid tier the user hasn't purchased.","commonSituations":"Trial bridges converting to paid; subscription card expiring mid-cycle; self-hosted bridge users lacking an institution license.","solutions":["Direct the user to their SimpleFin bridge billing page to restore the subscription","Verify which institution triggered it — sometimes only one bank is behind the paywall","Pause scheduled syncs for that connection until payment is resolved to avoid repeat failures","Rescue :payment_required separately from :access_forbidden so the user gets the right 'billing' message"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":"def simplefin_payment_required?(error)\n  error.is_a?(Provider::Simplefin::SimplefinError) && error.error_type == :payment_required\nend","tryCatchPattern":"begin\n  client.get_accounts(access_url)\nrescue Provider::Simplefin::SimplefinError => e\n  raise unless e.error_type == :payment_required\n  pause_connection!(reason: \"simplefin_billing\") # user action required; stop scheduling\nend","preventionTips":["Map :payment_required to a billing-specific user message, distinct from auth failures","Pause the connection's sync schedule after the first 402 rather than burning retries daily","Surface which institution is affected so the user knows what to pay for"],"tags":["simplefin","http-402","payment-required","billing","subscription"],"backgroundTag":"http-402-payment-required","analyzedSha":"e69894adb92547273377398c15f45c979cd9416a","analyzedAt":"2026-08-21T18:22:41.165Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}