Scoutinternal

ApiResponseError: 'Denied by Policy' and Other Withdrawal Errors on BitGo

ApiResponseError: "Denied by Policy" and Other Withdrawal Errors on BitGo

Problem

Customers attempting to withdraw or transfer funds from BitGo wallets encounter an ApiResponseError with messages such as "You have been denied by a policy," "exceeds per-transaction limit," "Cannot update locked policy," or generic server errors. These errors appear in both the BitGo web UI and API responses and affect multiple coin types (BTC, ETH, XRP, SUI, SOL, CSPR, and ERC-20 tokens). The error message typically includes an evaluation ID and an ErrorID, and directs the customer to contact support@bitgo.com. The root causes span whitelist misconfiguration, insufficient admin approvers, locked policies, transaction limit violations, and platform-side bugs.

Diagnostics

  • Identify the error message category. Ask for (or locate in the ticket) the exact ApiResponseError text. Key phrases to distinguish:
    • "You have been denied by a policy, provide this evaluation ID…" → policy denial
    • "exceeds per-transaction limit" → transaction limit policy
    • "Cannot update locked policy" → locked whitelist policy
    • "server error requestId=…" → platform-side / engineering issue
    • "Wallet is in state pendingEcdsaTssInitialization" → MPC/TSS setup incomplete
    • "webhook failed to return approval" → webhook-based approval policy failure
    • "method not implemented" or "Cannot read properties of null" → SDK/platform bug
    • "To enable <token> for your account, contact support@bitgo.com" → token not enabled
    • "Insufficient token allowance for batcher contract" → bulk send / batcher approval needed
  • Collect the wallet ID and enterprise ID from the customer or by looking up their account.
  • Check enterprise-level policies. In the admin tooling, look up the enterprise policy to see if a coinAddressWhitelist or advancedWhitelist rule exists that would deny the transaction outright.
  • Check wallet-level policies. Spoof or look up the wallet's admin.policy.rules array. Look for rules of type transactionLimit, velocityLimit, coinAddressWhitelist, or advancedWhitelist. Note the action field — deny vs. getApproval.
  • Check the number of admins on the wallet. If only one admin exists and the policy action is getApproval, the initiating admin cannot also approve — this results in an immediate denial.
  • Check whether the destination address is whitelisted at both the wallet level and the enterprise level (if an enterprise whitelist is active). A mismatch between the two causes denial.
  • Check if the policy is locked. Whitelist policies lock 48 hours after being set. If a pending approval was not completed before the lock, it will fail.
  • Check wallet type. V1 wallets (type safehd) have limited functionality and do not support secondary admins or user sharing.
  • Check the SDK version if the customer is using the API. Outdated SDK versions can cause method not implemented errors.

Resolution

Scenario: denied-evaluation-apiresponseerror-provide#destination-not-whitelisted-wallet

Trigger: The customer receives "denied by a policy" and the destination address is not whitelisted on the wallet's whitelist, while no enterprise whitelist is blocking.

Signals: denied by policy, evaluation ID, nonWhitelistedAddress, wallet whitelist, Whitelist tab

Steps:

  1. Confirm the destination address is not present in the wallet's "Whitelist" tab.
  2. Instruct the customer to navigate to the wallet, select the Whitelist tab, click + Whitelist, and add the destination address.
  3. For addresses requiring a destination tag (e.g., XRP), the full whitelisted address must include the tag in the format: r3ZDszz2ieaVjCPxGjMjJWrjVaxQxHgf1o?dt=123.
  4. Once the address is whitelisted, retry the withdrawal.

Notes: This is the most common root cause for FTX/Go account users. Many of these customers are unfamiliar with the whitelisting requirement.

"To withdraw from your Go account, please ensure that the destination address is whitelisted in the 'Whitelist' tab of your Go account. If the address requires a destination tag, be sure to include it when adding the address to the whitelist."

Scenario: denied-evaluation-apiresponseerror-provide#destination-not-whitelisted-enterprise

Trigger: The destination address is whitelisted at the wallet level but NOT at the enterprise level, or vice versa, and an enterprise whitelist policy is active.

Signals: denied by policy, enterprise whitelist, nonWhitelistedAddress, enterprise and wallet whitelists, enterprise settings

Steps:

  1. Confirm an enterprise-level whitelist policy exists by checking enterprise settings > Policy.
  2. Verify whether the destination address appears in the enterprise whitelist.
  3. If the address is missing from the enterprise whitelist: instruct the customer to log in, click the Profile Icon, choose Enterprise Settings, select the Whitelist tab, and add the address.
  4. If the address is only at the enterprise level but not the wallet level (for custodial wallets): instruct the customer to also add it to the wallet-level whitelist.
  5. Enterprise policy violations are an immediate denial — they do not generate a pending approval. Wallet policy violations prompt for admin approval.

Notes: When an enterprise whitelist is enabled, all wallet-level whitelists must only include addresses that are already part of the enterprise whitelist.

"It appears that the address you're trying to send funds to is whitelisted at the wallet level but not at the enterprise level. When an enterprise whitelist is enabled, all wallet-level whitelists must only include addresses that are already part of the enterprise whitelist." "You have whitelisted the address at an Enterprise level, but this needs to be Whitelisted at a wallet level. Enterprise policy violations are an immediate denial, while Wallet policy violations will prompt for admin approval."

Scenario: denied-evaluation-apiresponseerror-provide#single-admin-cannot-self-approve

Trigger: The wallet has only one admin, and the withdrawal triggers a policy that requires admin approval — the initiating admin cannot also approve.

Signals: denied by policy, single admin, cannot approve own transaction, add a second Admin, getApproval

Steps:

  1. Confirm the wallet has only one admin by checking the wallet's user list.
  2. Explain to the customer: "An Admin who initiates a transaction cannot also provide the Admin approval."
  3. Advise the customer to either:
    • Whitelist the destination address on the wallet to avoid triggering the approval requirement, OR
    • Add a second admin to the wallet so that the second admin can approve the transaction.
  4. The customer can add a second admin by navigating to the wallet settings and inviting another user with admin permissions. They may use a second email address they control if no other team member is available.
  5. After adding the second admin, re-initiate the withdrawal. The second admin will receive a notification to approve the pending transaction.

Notes: This scenario commonly occurs when a non-whitelisted address triggers a policy requiring approval but no second admin is available. It also applies when velocity limits are exceeded.

"Policy triggered because the address you are attempting to send to is not whitelisted on the wallet which in turn triggers the need for an Admin Approval. This action is being denied because there is only a single Admin on the wallet. An Admin who initiates a transaction cannot also provide the Admin approval. Corrective actions are either to whitelist the address on the wallet or to add a second Admin." "Since you have added this address as a whitelist you can only withdraw funds to this address. If you wish to withdraw on any other address they you need to add other user as admin on your wallet and bypass this policy. You can add your own 2nd email as admin and can approve the transaction once it's triggered 2nd admin approval in order to bypass the policy."

Scenario: denied-evaluation-apiresponseerror-provide#locked-whitelist-policy

Trigger: The customer receives "Cannot update locked policy" when trying to approve a pending whitelist change, or a policy change approval was not completed before the 48-hour lock window expired.

Signals: Cannot update locked policy, locked, 48 hours, unlock, Calendly, video ID, videoid

Steps:

  1. Confirm the policy is locked by checking the policy's mutableUpToDate field. Whitelist policies lock 48 hours after being first set.
  2. If the customer needs to make changes to a locked policy, they must schedule a video verification call with BitGo.
  3. Provide the scheduling link: https://calendly.com/bitgo-client-delivery/videoid
  4. During the call, BitGo will verify the identity of an authorized user and unlock the policy for a specified duration (between 1 and 48 hours).
  5. Only verified and authorized users on the enterprise can attend the call. Confirm which users are authorized before the customer schedules.
  6. Once unlocked, all policy changes must be completed and all approvals gathered within the unlock window.

Notes: If a whitelist change approval was submitted before the lock but not all approvals were collected by the time the policy locked, the approval will fail. A new unlock is required to resubmit.

"For Whitelist policies, these lock 48 hours after being set for the first time. From there, your team can meet with us to further unlock for a duration between 1 hours and 48 hours." "If all approvals are not in by the unlock expiry, this error will be returned indicating an unlock is further needed to allow the approval for the changes."

Scenario: denied-evaluation-apiresponseerror-provide#exceeds-per-transaction-limit

Trigger: The customer receives "exceeds per-transaction limit" when attempting a withdrawal.

Signals: exceeds per-transaction limit, transactionLimit, velocity limit, v1 wallet

Steps:

  1. Look up the wallet's policy rules. Check for a transactionLimit rule with a condition.amount value.
  2. If the limit is set to 0 or an unreasonably low value, the customer may need to adjust or remove the policy.
  3. For v1 wallets: v1 wallets are deprecated and have limited UI policy visibility. Advise the customer to create a new v2 wallet and sweep funds from the v1 wallet to the v2 wallet. From the v2 wallet, they can set appropriate policies and withdraw normally.
  4. For v2 wallets: If the policy is not visible in the UI but exists in the backend (check admin.policy.rules in the wallet object), escalate to engineering to investigate and resolve.
  5. Alternatively, the customer can add a second admin to approve transactions that exceed the limit, or adjust the policy limit if the policy is unlocked.

Notes: Some legacy wallets have hidden policies (e.g., transactionLimit set to 0) that do not display in the UI. If the customer states they cannot see any policy but the error persists, check the wallet object via admin tools and escalate if needed.

"As part of our ongoing improvements, we have deprecated v1 wallets and completely disabled the ability to create new v1 wallets, both via API and the web UI, as well as any related functionality. You will need to create a new wallet which will be a v2 wallet, and you can transfer the v1 balance to the new v2 wallet."

Scenario: denied-evaluation-apiresponseerror-provide#pending-ecdsa-tss-initialization

Trigger: The error message states "Wallet is in state pendingEcdsaTssInitialization. Please contact your enterprise admin to finish the tss setup."

Signals: pendingEcdsaTssInitialization, tss setup, MPC, Create Challenge

Steps:

  1. An enterprise admin must complete the MPC (TSS) setup before the wallet can process withdrawals.
  2. Instruct the admin to log in to the platform, click the profile icon in the upper right, then choose Settings.
  3. Scroll down to the Wallets section and find Enable MPC.
  4. Click Create Challenge and complete the process.
  5. Once the challenge is created, retry the withdrawal.

Notes: This is required for wallets on newer MPC-based coin types (e.g., SEI). Any enterprise admin can complete this step.

"Can you have Tom or Graham login to the platform, choose the profile icon in the upper right and then choose settings. Once there, scroll down until you find the Wallets section, Enable MPC. Choose Create Challenge. Once this is completed, please retry the withdrawal."

Scenario: denied-evaluation-apiresponseerror-provide#webhook-approval-policy-failure

Trigger: The error includes "webhook failed to return approval" with a response body showing an HTTP redirect or unrelated URL.

Signals: webhook failed to return approval, webhook, v1 wallet, safehd, getApproval, noty-tut.ru

Steps:

  1. This error occurs when a wallet has a webhook-based approval policy (webhook:getApproval) and the configured webhook URL is no longer responding correctly (e.g., returning an HTTP 301 redirect).
  2. Check the wallet type. If it is a V1 wallet (safehd type): V1 wallets do not support secondary admins or user sharing. Only the original admin can withdraw funds.
  3. Advise the customer to create a new BTC V2 wallet and sweep the funds from the V1 wallet to the V2 wallet.
  4. If the customer cannot sweep due to the same webhook error, escalate to engineering (reference JIRA tickets for V1 wallet webhook issues) and schedule a video verification call to assist.
  5. Once funds are in the V2 wallet, the customer can set desired policies on the V2 wallet.

Notes: V1 wallets are deprecated. The long-term fix is always migration to a V2 wallet.

"V1 wallets do not support secondary admins or user sharing; all admins must be removed for approvals to work. Only the original admin can withdraw funds from V1 wallets. Additionally To resolve this error, please create a new BTC V2 wallet and sweep the funds from the V1 wallet to the V2 wallet."

Scenario: denied-evaluation-apiresponseerror-provide#enterprise-whitelist-deny-rule-api

Trigger: An API customer receives "error":"denied by policy" with a triggeredPolicy ID, and the enterprise has a coinAddressWhitelist rule with action deny.

Signals: denied by policy, triggeredPolicy, coinAddressWhitelist, deny, enterprise policy, API

Steps:

  1. Look up the enterprise policy using the enterprise ID and the triggeredPolicy ID from the error response.
  2. Identify the coinAddressWhitelist rule. This rule restricts all withdrawals for a specific coin to only the addresses listed in the whitelist.
  3. The customer must either:
    • Add the desired destination address to the enterprise whitelist rule, OR
    • Remove the restrictive rule if it is no longer needed.
  4. Policy changes to a locked enterprise policy require a video verification call to unlock. Provide the scheduling link: https://calendly.com/bitgo-client-delivery/videoid

Notes: Enterprise-level deny rules cannot be overridden by wallet-level settings. The enterprise whitelist takes precedence.

"This rule will only allow sending to addresses…for all ETH withdrawals from all wallets in the enterprise. You can either remove this rule or add the address(es) you want to send to to the whitelist."

Scenario: denied-evaluation-apiresponseerror-provide#token-not-enabled

Trigger: The error states "To enable for your account, contact support@bitgo.com."

Signals: To enable, token, bbtc, enable for your account, contact support

Steps:

  1. The customer is trying to withdraw a token (e.g., BBTC) that is not enabled for their account/enterprise.
  2. Enable the token for the customer's account using internal admin tooling.
  3. Confirm with the customer that the token is now enabled and ask them to retry the transaction.

Notes: This can happen when a customer receives an unexpected token to their wallet (e.g., a user sent BBTC instead of USDT by mistake) and the token type was not previously enabled for the enterprise.

Scenario: denied-evaluation-apiresponseerror-provide#server-error-engineering-escalation

Trigger: The error is a generic server error requestId=… without a policy denial message, or contains messages like "Cannot read properties of null (reading 'prices')," "missing unspent," "method not implemented," "The value of 'offset' is out of range," or "Failed to get input objects from serialized transaction."

Signals: server error, requestId, 500, missing unspent, offset out of range, Cannot read properties of null, method not implemented, Failed to get input objects, engineering

Steps:

  1. Collect the full requestId and/or ErrorID from the customer.
  2. Ask for the wallet ID, coin type, and whether the action was via API or UI.
  3. If via API, request the full endpoint called, SDK version, and payload (with sensitive data redacted).
  4. Look up the requestId in internal logging tools (Grafana/Kibana) to identify the specific backend error.
  5. Escalate to the Engineering team with the requestId, wallet ID, coin type, and error details.
  6. Keep the customer informed of progress and relay the engineering team's findings.
  7. For missing unspent errors on UTXO chains (BTC, BCH, LTC): advise the customer to rebuild the transaction and process withdrawals in sequence, as concurrent withdrawals can consume the same unspent.
  8. For method not implemented errors via SDK: advise the customer to update to the latest SDK version and retry.

Notes: These are platform-side bugs or transient issues. Resolution timelines depend on engineering. Some have been resolved by deploying fixes to production. For BCH specifically, replay protection changes have caused concurrent withdrawal issues.

Scenario: denied-evaluation-apiresponseerror-provide#maintenance-or-connectivity

Trigger: The error includes "ECONNREFUSED" or occurs during a period listed on the BitGo status page.

Signals: ECONNREFUSED, connect ECONNREFUSED, maintenance, status.bitgo.com, deposits and withdrawals down

Steps:

  1. Check the BitGo status page: https://status.bitgo.com/
  2. If an active maintenance window or incident is listed, inform the customer that the error is due to ongoing maintenance.
  3. Advise the customer to retry once the maintenance window has concluded.
  4. If no maintenance is listed, collect the requestId and escalate to engineering.

Notes: During scheduled maintenance, the application may be unavailable for ~10 minutes with elevated error rates for ~30 additional minutes.

Scenario: denied-evaluation-apiresponseerror-provide#no-account-found-possible-scam

Trigger: No BitGo account is found under the customer's email address, or the customer appears to be using an unofficial URL.

Signals: no account, not registered, different email, scam, unofficial URL, phishing

Steps:

  1. Verify whether the customer's email is registered on the BitGo platform.
  2. If no account is found, ask the customer to confirm the URL they are using to log in. The official domain is https://www.bitgo.com/ and the login portal is https://app.bitgo.com/web/auth/login.
  3. If they are accessing via a different URL, warn them they may not be on the legitimate BitGo platform.
  4. Note that BitGo provides support exclusively via email — there is no phone support line or online chat support.
  5. Official mobile app links:
    • Apple App Store: https://apps.apple.com/us/app/bitgo/id1608937235
    • Google Play Store: https://play.google.com/store/apps/details?id=com.bitgo.mobile&hl=en_US

Notes: This pattern is common with users who may have been directed to a fraudulent site impersonating BitGo.

Related