Synchronous Ledger Entry Rate Limiting

The Ledgers API supports 100 QPS on all read and write APIs, and higher rate limits are available upon request. In addition to these standard rate limits, we also rate limit synchronous Ledger Entries at a rate of 20 Ledger Entries per Ledger Account per second. A Ledger Entry is synchronous if any of the following conditions are true:

• One of these fields is set on the Ledger Entry at creation: pending_balance_amount, posted_balance_amount, available_balance_amount, or lock_version. See Handling Concurrency for information about these fields.
• The show_resulting_ledger_account_balances field is set to true on the Ledger Entry at creation.

We rate limit synchronous Ledger Entries because they require a lock on the associated Ledger Account and must be processed serially. In order to avoid high latency and rate limiting at high throughputs, you must architect your ledger to avoid the “hot account” problem.

A hot account is a Ledger Account that receives a high volume of Ledger Entries. Many ledger architectures include a hot account to represent operating cash or a common settlement account. For example a typical transaction for a debit card program may look like:

While Alice’s Debit Card may only be transacting a few times per day, the Issuing Bank Nightly Settlement Account is credited every time there is a transaction across the whole card program. This account is likely to see a high volume of Ledger Entries, but these entries can be processed asynchronously. The entry on Alice’s Account needs to perform a balance check so must be processed synchronously.

📘

Key takeaway

When you’re writing to a single Ledger Account at a high throughput (a “hot account”), don’t write the Ledger Entries with balance or lock_version conditions, and don’t use the show_resulting_ledger_account_balances flag. All Ledger Entries will be applied to the associated Ledger Account balance within 60 seconds.

If you want to get the list of Ledger Entries that have been processed on a Ledger Account, fetch the Ledger Account and pass the returned lock_verson to List Ledger Entries in the as_of_lock_version parameter.

When updating a Ledger Transaction without sending new Ledger Entries, all Ledger Entries which were originally created synchronously will automatically be updated synchronously. If the update replaces the Ledger Entries, they will be synchronous based on the new parameters.