Scoutinternal

Spending Limits, Rate Limits, and Double Spend Errors

Spending Limits, Rate Limits, and Double Spend Errors

Problem

Customers encounter several categories of limit-related issues on the BitGo platform: (1) wallet spending/velocity policy limits that block or hold transactions, requiring a policy unlock; (2) API rate limits (HTTP 429) when calling BitGo endpoints too frequently; (3) "transaction attempted to double spend" errors during BTC withdrawals, caused by the platform's indexer failing to mark unspent transactions promptly; (4) enterprise-level wallet creation limits that cap how many wallets can exist per coin; and (5) custom fee rate and address creation rate limits. These issues affect multiple coins (primarily BTC, but also LTC, ETH, TRX, and others) and surface through both the UI and API.

Diagnostics

  • Identify the category of limit issue. Ask the customer for the exact error message or HTTP status code. Key distinguishing signals:
    • "transaction attempted to double spend" → double spend / indexer issue
    • HTTP 429 / "Too many requests, slow down!" / "Client request rate exceeded the limit" → API rate limit
    • "Exceeds spending limit" or transaction in state=held → wallet spending/velocity policy limit (circuit breaker tripped)
    • Wallet creation failure → enterprise wallet creation limit
    • Deposit blocked or rejected → check account type; individual accounts have a $25,000 USD/day deposit limit
  • For double spend errors: Check https://status.bitgo.com/ for any active BTC incidents. Ask the customer for the wallet ID and confirm whether they have multiple pending approvals or are sending transactions in rapid succession from the same wallet.
  • For API rate limits (429): Ask for:
    • Full endpoint being called along with method used
    • Full error log returned along with requestID
    • Bitgo Express/SDK Version
    • NPM Version
    • Email address of the user who created the API Access Token being used to authenticate
  • For spending/velocity policy limits (stuck/held transactions): Look up the wallet in admin tools. Check the enterprise policy and whether a circuit breaker has been tripped. Inspect the send queue for transactions in state=held.
  • For wallet creation limits: Look up the enterprise's walletLimit configuration in admin tools. Check existing wallet counts per coin against the configured limits.
  • For address creation rate limits: Note that the typical limit is 1 address per second. Check if the customer is calling the create-address endpoint faster than this rate.

Resolution

Scenario: limit-limits-spending-rate#deposit-limit-by-account-type

Trigger: Customer reports a deposit is being blocked or asks whether there is a limit on how much they can deposit per day.

Signals: deposit limit, daily limit, deposit blocked, how much can I deposit, individual account, entity account, deposit cap, 25000, 25k

Steps:

  1. Confirm the customer's account type (Individual or Entity) by looking up their enterprise in admin tools.
  2. Inform the customer of the applicable deposit limits:
    • Individual accounts: $25,000 USD deposit limit per day.
    • Entity accounts: No deposit limit.
  3. If an individual account customer needs to deposit more than $25,000 USD in a day, advise them that the limit cannot be exceeded for individual accounts. If they have ongoing high-volume deposit needs, direct them to the Sales team to discuss upgrading to an entity account: https://www.bitgo.com/connect-with-us
  4. If the deposit was blocked due to the daily limit being reached, advise the customer to retry the deposit on the following day.

Notes: The $25,000 USD/day deposit limit applies to individual account types only. Entity accounts do not have a deposit limit.

Scenario: limit-limits-spending-rate#double-spend-indexer

Trigger: Customer reports "transaction attempted to double spend" errors when sending BTC transactions.

Signals: double spend, transaction attempted to double spend, BTC send failure, unspents, indexer, pending approvals

Steps:

  1. Check https://status.bitgo.com/ for any active incidents related to BTC or the indexer.
  2. If a platform-wide incident is active, inform the customer that the engineering team is investigating and direct them to the status page for updates.
  3. If no platform-wide incident is active, explain the error: "This error occurs when the transaction that you create attempts to spend an unspent that has already been used in a prior transaction. Often this is related to not having enough unique unspents in your wallet and having multiple pending approvals for transactions on your wallet at the same time."
  4. Advise the customer to approve transactions in the order they are created and ensure they have enough unspents in the wallet.
  5. If the issue is widespread across multiple customers, escalate to Engineering. Historical root cause has been a slow indexer marking unspent BTC transactions; Engineering has deployed patch fixes for this in the past.
  6. If the issue persists for the individual customer after confirming no platform incident, collect the wallet ID, transaction IDs / requestIDs, and timestamps, then escalate to Engineering.

Notes: This error has historically occurred as a platform-wide incident affecting multiple customers simultaneously. Past incidents were tracked at https://status.bitgo.com/incidents/dsbkhqcn3gq1. The root cause was a slow indexer marking unspent BTC transactions; Engineering deployed a patch fix. If the customer has a high volume of transactions, recommend consolidating unspents during low-fee periods.

"This error occurs when the transaction that you create attempts to spend an unspent that has already been used in a prior transaction. Often this is related to not having enough unique unspents in your wallet and having multiple pending approvals for transactions on your wallet at the same time. Please be sure to approve transactions in the order they are created and that you have enough unspents in your wallet to accomplish these transactions." (ticket #82071)

"The issue was due to slow indexer marking unspent BTC transactions. Our Engineering team has already made a patch fix on this and should not have this type of issue moving forward." (ticket #71288)

"Unfortunately, our platform has ran into some technical issues with BTC and which was throwing a 'Double spend' error for a couple of hours for our BTC withdrawals. The issue for the double spend error has been fixed now. However, due to the technical issue hour, the BTC indexer was also impacted and there is a slowness in BTC transaction processing." (ticket #222861)

Scenario: limit-limits-spending-rate#api-rate-limit-429

Trigger: Customer receives HTTP 429 status code or "Too many requests, slow down!" when calling BitGo API endpoints.

Signals: HTTP 429, rate limit, Too many requests, slow down, Client request rate exceeded the limit, API rate, 429 Too Many Requests

Steps:

  1. Verify the customer has an account on the BitGo platform and that the request is coming from an authorized user. For security, support can only assist users with accounts on the platform.
  2. Confirm which endpoint is being called. Public (unauthenticated) endpoints have lower rate limits than authenticated (customer) endpoints.
  3. Share the API rate limit documentation: https://developers.bitgo.com/api/overview
  4. Inform the customer of standard rate limits:
    • Authenticated user endpoints: 360 requests per 60 seconds (6 per second). This limit is per user — if a user creates 2 access tokens, the rate limit of 360 requests/min applies across both tokens combined.
    • Custom API endpoints (e.g., dedicated customer endpoints) may have higher limits. One example observed: 4,000 requests per 10 seconds, with a 10-second block (per IP).
  5. If the customer requests a rate limit increase, collect:
    • Email addresses of the users for whom the rate limits need to be adjusted
    • The new limit requested
    • Business justification for the increase
    • Evidence of hitting the rate limit (full endpoint, method, error log with requestID)
  6. If a rate limit increase is approved, coordinate with Engineering / Solutions Engineering (se@bitgo.com) to apply the change.
  7. For customers using a dedicated/custom API endpoint, an IP may need to be whitelisted. Collect the IP address and the custom API endpoint URL, obtain CTO/authorized approval from the customer's organization, and coordinate with Engineering.

Notes: Rate limits are set on a per-user basis, not per API key. If one user has multiple API keys/tokens, the limit is shared across all of them. Customers sharing API usage across multiple integrations (e.g., admin + third-party PMS) under the same user should be aware of this. Recommending separate "Application Users" for different integrations can help avoid contention.

"As long as you are using the customer endpoint, you will enjoy higher rate limits compared to the public endpoints. Please note your account currently has the custom API with the following limit: Production API: 4,000 requests per 10 seconds, with a 10-second block (per IP)." (ticket #239293)

"The rate limits are set on a per user basis. This is to say, if your user creates 2 access tokens, your rate limit is 360 requests /min across the two tokens." (ticket #241386)

"Could you please share the email addresses of the users for whom the rate limits need to be adjusted? Additionally, let us know the new limit you would like to request and provide the business justification for this increase." (ticket #320423)

Scenario: limit-limits-spending-rate#spending-policy-unlock

Trigger: Customer requests a change to their wallet spending limit, or a transaction is stuck/held because it tripped a circuit breaker or velocity limit.

Signals: spending limit, limit change, velocity limit, circuit breaker, state=held, stuck transaction, enterprise policy unlock, wallet policy

Steps:

  1. Look up the wallet and enterprise in admin tools. Check if a circuit breaker has been tripped (look for transactions in state=held in the send queue).
  2. Inform the customer that a video ID verification call is required to unlock the wallet policy or release held transactions.
  3. Provide the Calendly scheduling link: https://calendly.com/bitgo-client-delivery/videoid
  4. Instruct the customer to have a valid government-issued photo ID ready for the call. Ask them to reference their ticket/case number when scheduling.
  5. After completing the video verification, unlock the wallet policy and release any held transactions.
  6. If the customer needs the enterprise spending limit raised to prevent future stuck transactions, request a written request from the customer, then coordinate internally to update the enterprise limit configuration.

Notes: Enterprise limit increases require a written request from the customer. After releasing stuck transactions, proactively discuss raising the enterprise limit to prevent recurrence.

"We have received your request to unlock your wallet policy. For security purposes, we will need to schedule a video conference to verify your Identification. Please use the following link to schedule a time to meet with us and verify the request: https://calendly.com/bitgo-client-delivery/videoid. Please be ready to provide your government issued photo ID during this meeting." (ticket #214887)

"Thank you for meeting with us, we have released your stuck transactions. As discussed in the call, we will get back to you on the steps required to raise your enterprise limit to deter further stuck transaction." (ticket #276061)

Scenario: limit-limits-spending-rate#wallet-creation-limit

Trigger: Customer plans to create multiple wallets and wants to verify they will not hit enterprise wallet creation limits, or receives an error when creating a new wallet.

Signals: wallet creation, wallet limit, walletLimit, capacity limit, enterprise limit, number of wallets

Steps:

  1. Look up the enterprise's walletLimit configuration in admin tools. The limits are set per coin and may include entries like "ofc", "xrp", "eos", "hbar", etc.
  2. Count the existing wallets on the enterprise per coin and compare against the configured limits.
  3. Inform the customer of any coins where the planned wallet creation would exceed the limit.
  4. If limits need to be raised, coordinate internally to update the enterprise walletLimit configuration.
  5. Note: Some coins (e.g., BTC) may not have an explicit wallet limit on certain enterprises. Qualified Custody wallets may not be subject to the same limits.

Notes: Not all coins have wallet creation limits. The limit structure varies by enterprise. If no limit is established for a particular coin or wallet type, additional wallets should not trigger any limits.

"I am not showing a limit established on this Enterprise for number of Qualified Custody wallets. It does not appear these additional wallets will trigger any limits... Current Limits for this Enterprise for number of wallets: "ofc": 1, "xrp": 5, "eos": 10, "hbar": 100" (ticket #167988)

Scenario: limit-limits-spending-rate#address-creation-rate-limit

Trigger: Customer receives "Too many requests, slow down!" or AggregateError when creating addresses via API.

Signals: address creation, AggregateError, Too many requests, create address, 1 address per second, ETH address creation

Steps:

  1. Inform the customer that the typical rate limit for address creation is 1 address per second.
  2. Direct them to the rate limit documentation: https://developers.bitgo.com/api/overview
  3. Advise the customer to reduce the frequency of address creation API calls to stay within the limit.
  4. If the customer needs clarification on whether the ETH-specific address creation rate limit applies to non-ETH chains, note that the 1 address per second limit appears to be general. However, if the customer is still hitting limits on non-ETH chains (BTC, DOGE, etc.) despite staying below 360 requests/min, escalate to Engineering for clarification on undocumented per-chain address creation limits.

Notes: The customer in ticket #239562 resolved the issue by reducing the number of calls to the API. The ETH address creation limit may differ from other chains, but the 1 address per second guidance was provided as a general rule.

"Regarding address creation, the typical limit is 1 address per second." (ticket #239562)

Scenario: limit-limits-spending-rate#custom-fee-rate

Trigger: Customer asks about setting a maximum sat/vB fee rate per transaction, or has a BTC transaction stuck due to a low fee.

Signals: sat/vB, fee rate, low fee, stuck transaction, custom fee, network commission, accelerate transaction

Steps:

  1. Explain that a custom fee rate can be set in the withdrawal screen by expanding the "Additional Parameters (Optional)" option in the UI.
  2. For API users, the fee rate can be set via the send endpoint: https://developers.bitgo.com/api/express.wallet.sendcoins
  3. Warn the customer: if network fees are higher than their customized fee rate, the transaction may get stuck and not confirm until network fees drop to the range of the transaction fee. This could take a long time.
  4. If a transaction is already stuck due to a low fee, the customer can accelerate it:
  5. Refer the customer to https://jochen-hoenicke.de/queue/#BTC,4d,fee for current fees on the BTC network.

Notes: This applies primarily to UTXO chains (BTC, LTC, etc.). If the fee is set too low, the transaction will eventually proceed to chain and confirmation when fees come down, without further action — but the wait can be long.

"You can set High priority or your own custom fee rate in the withdrawal screen when you expand the 'Additional Parameters (Optional)' option." (ticket #251112)

"If the fee is too low, it may not be prioritized until that cost comes down. When fees come down to the range of the transaction, it should proceed to chain and confirmation without further action. You can also use our accelerate transaction endpoint to help move this along. https://developers.bitgo.com/api/express.wallet.acceleratetx" (ticket #217195)

Scenario: limit-limits-spending-rate#trx-spendable-consolidation

Trigger: Customer reports that the spendable amount for a TRX token (e.g., USDT on TRX) is less than the confirmed amount.

Signals: spendable, confirmed, TRX, USDT, consolidation, consolidate, receive address

Steps:

  1. Explain that the spendable amount is less than the confirmed amount because funds are distributed across multiple receive addresses that have not been consolidated to the root address.
  2. Instruct the customer to consolidate:
  3. Explain that each receive address holding the token (e.g., TRX:USDT) must have sufficient TRX to cover the consolidation fee. The TRX at the root address cannot cover fees for other receive addresses.
  4. Provide estimated consolidation fees:
    • (2.1 TRX) for TRX
    • (35.834875 TRX) for USDT token
    • (17.0215 TRX) for USDC token
  5. Warn that if a consolidation fails, the fee is still consumed.

Notes: On the TRON blockchain, each receive address is an independent account. The customer must fund each receive address with enough TRX before consolidating tokens from it.

"When consolidating a TRX address, the consolidation fee is paid in TRX as well. Each address being consolidated needs to hold enough TRX to cover the fee cost. Please note, if a consolidation fails, the fee is still consumed. Estimated cost is shown below: (2.1 TRX) for TRX, (35.834875 TRX) for USDT token, (17.0215 TRX) for USDC token." (ticket #323133)

Related

  • bitcoin-consolidation — Consolidating unspents is directly relevant to preventing double spend errors and managing UTXO wallets.
  • bitcoin-special-call-outs — Best practices for BTC hot wallet management including fee calculation and transaction throughput.
  • keycards-and-private-keys — Warm wallet vs. hot wallet policy configuration, including whitelist policies that interact with spending limits.