Scoutinternal

BitGo API v2 Endpoint Integration: Common Errors and Troubleshooting

BitGo API v2 Endpoint Integration: Common Errors and Troubleshooting

Problem

Customers integrating with the BitGo API v2 encounter a range of issues including HTTP 401, 403, 404, 500, 503, and 504 errors, incorrect parameter usage (e.g., confusing Enterprise ID with Account ID or Wallet ID), missing permissions on access tokens, OTP/unlock requirements when sending transactions via API, and general confusion about API documentation, access token creation, and the difference between BitGo Express and SDK endpoints. These issues span production and test environments across multiple coins and affect both new integrators and established enterprise clients.

Diagnostics

  • Identify the environment: Confirm whether the customer is working in Test (test.bitgo.com) or Production (app.bitgo.com). Test environment outages are separate from production.
  • Collect full request details: Ask for the full endpoint as called (including base URL and HTTP method), full payload (minus passwords/passphrases), and full response including error body and reqId.
  • Check the HTTP status code and error body:
    • 401 with "needsOTP": true, "needsUnlock": true → spending limit / unlock issue.
    • 403 → permissions or wrong ID used (e.g., Enterprise ID instead of Account ID).
    • 404 → wrong coin ticker in path or wallet not found under that coin.
    • 500 with "error":"Internal Server Error" → may be a server-side issue; check reqId and escalate if persistent.
    • 503 Service Temporarily Unavailable → platform outage; check https://status.bitgo.com/ and internal Slack alerts.
    • 504 → gateway timeout, typically a test environment infrastructure issue.
  • Check user permissions: In the admin console, verify the user associated with the access token has permissions on the relevant enterprise and wallets. A user with enterprise-level "View all wallets" may still lack per-wallet granular permissions for certain API calls.
  • Check access token configuration: Verify the access token's IP whitelist includes the public IP(s) of the caller, and that the token has the appropriate permission scopes (read, spend, admin).
  • Check coin/token enablement on the enterprise: Some wallet types (e.g., MPC/TSS wallets) require backend enablement (e.g., ethTSS) on the enterprise before creation succeeds.
  • Check Express/SDK version: Ask for the BitGo Express or SDK version in use, especially for errors like ApiResponseError coming from Express middleware.
  • Check status page: https://status.bitgo.com/ for known incidents matching the customer's error timeframe.

Resolution

Scenario: api-v2-endpoint-integration#wrong-id-parameter

Trigger: Customer receives HTTP 403 or empty results when calling trading or wallet endpoints because they are passing their Enterprise ID where an Account ID or Wallet ID is required.

Signals: 403, forbidden, account_id, Enterprise ID, empty response, no data, trading endpoint, Order Book

Steps:

  1. Confirm which endpoint the customer is calling and which ID parameter it expects.
  2. For trading endpoints (e.g., /api/prime/trading/v1/accounts/{accountId}/...), the {accountId} is not the Enterprise ID. Instruct the customer to use their Go Account Wallet ID or retrieve it via the List Accounts endpoint: https://developers.bitgo.com/api/trade.accounts
  3. For wallet-level endpoints, the {walletId} must be the specific wallet's ID, not the enterprise ID.
  4. If the customer cannot retrieve their Account ID, direct them to start with the List Enterprises endpoint (https://developers.bitgo.com/api/enterprise.list) to get their Enterprise IDs, and then call the wallets endpoint passing the Enterprise ID as a query parameter.

Notes: This is one of the most common integration mistakes. The Enterprise ID is visible in settings and customers often assume it is the account/wallet ID.

"Account ID is not your Enterprise ID. You can use the following endpoint to list your Account ID. https://developers.bitgo.com/api/trade.accounts" (ticket #223644)

"For the Account ID in the endpoint, please use the Go Account Wallet ID. For the Access Token, please insure the IP/s configured in the restriction is the Public IP/s of the user/s that are calling this endpoint." (ticket #87684)

Scenario: api-v2-endpoint-integration#needs-unlock-otp

Trigger: Customer receives HTTP 401 with "needsOTP": true, "needsUnlock": true when attempting to send a transaction via API.

Signals: 401, needs unlock, needsOTP, needsUnlock, OTP, spending limit, transfer, send

Steps:

  1. Explain that the access token requires a lifetime spending limit configured for each coin/token that will be sent in order to bypass the OTP requirement on send calls.
  2. Instruct the customer to set a spending limit for the relevant coin. For example, if sending from a Polygon wallet, set a Polygon spending limit on the access token.
  3. The spending limit can be configured when creating or editing the access token under Developer Options in the BitGo web UI.

Notes: This applies to all send/transfer operations via API. Without a spending limit, each send will require an interactive OTP unlock.

"To bypass OTP in these calls, the Access Token will need a lifetime spending limit configured for each coin/token that will be sent. Since this is a Polygon wallet and would be a Polygon NFT, you should be able to set a Polygon spending limit to resolve this issue." (ticket #113684)

Scenario: api-v2-endpoint-integration#mpc-tss-wallet-creation-blocked

Trigger: Customer receives error "For MPC wallet creation, please contact support@bitgo.com" when trying to create wallets via API.

Signals: MPC, wallet creation, ethTSS, TSS, permission, enterprise, contact support

Steps:

  1. Check the customer's enterprise ID in the admin tooling.
  2. Verify whether TSS (e.g., ethTSS) is enabled on their enterprise.
  3. If not enabled, enable the appropriate TSS feature flag on the enterprise backend.
  4. Ask the customer to retry wallet creation.

Notes: This is a backend permissions issue, not a customer configuration error. The fix must be applied by BitGo support or engineering.

"enabled ethTSS on the ENT" (ticket #113684)

"Can you try again? Looks like a permissions issue that we have since changed on the back end." (ticket #113684)

Scenario: api-v2-endpoint-integration#503-platform-outage

Trigger: Customer receives HTTP 503 "Service Temporarily Unavailable" from nginx on multiple API endpoints simultaneously.

Signals: 503, Service Temporarily Unavailable, nginx, outage, platform, listtransfers, auditlog

Steps:

  1. Check https://status.bitgo.com/ for any active or recent incidents matching the timeframe.
  2. Check internal Slack channels (e.g., #alerts) for 5xx spike alerts or infrastructure incidents.
  3. If an incident is confirmed, inform the customer that engineering is aware and provide the status page link.
  4. If the customer requests a root-cause analysis (RCA), file an internal request to the engineering/SRE team and relay findings once available.

Notes: Known past causes include: (a) network packet drops triggering a database operator into a bad state, causing platform-mongo and the Wallet Platform to go unavailable (fix: restart service operator to auto-restore config); (b) DNS infrastructure upgrade with human error causing internal DNS resolution failures (fix: correcting DNS config, then automating the upgrade process).

"There was a network issue which caused packet drops. The pocket drops kicked one of our service operator into a bad state. Malfunctioned service operator committed a broken replica set that affected our platform database. Due to that broken config our Wallet Platform was affected that causes the 503 error. Resolution: Restart service operator and it automatically restored platform-db to correct configuration and everything was recovered." (ticket #192457)

"Root cause - During a routine maintenance, we upgraded our DNS infrastructure. Due to a human error, we experienced internal DNS resolution issues during a few minutes, affecting the ability of our applications to talk to each other. How it was fixed - correcting our DNS configurations. Measures to prevent recurrence - we have automated the task that the human was performing." (ticket #318709)

Scenario: api-v2-endpoint-integration#504-test-environment

Trigger: Customer receives HTTP 504 errors across most API requests specifically in the test environment.

Signals: 504, test environment, timeout, gateway timeout, test.bitgo.com

Steps:

  1. Confirm the issue is isolated to the test environment (test.bitgo.com).
  2. Check internal Slack channels and status page for test environment incidents.
  3. Escalate to the engineering team if no known incident is posted.
  4. Inform the customer that engineering is investigating and provide updates as available.

Notes: Test environment outages are handled separately from production and may not always appear on the public status page.

Scenario: api-v2-endpoint-integration#500-internal-server-error

Trigger: Customer receives HTTP 500 "Internal Server Error" with a reqId, and the error persists after correcting IDs and IP whitelisting.

Signals: 500, Internal Server Error, reqId, server error, persistent

Steps:

  1. Collect the reqId value from the error response and the exact timestamp of the request.
  2. Confirm the customer is using the correct IDs (wallet ID vs. enterprise ID vs. account ID) and that IP whitelisting is correct.
  3. If the error persists after customer-side corrections, escalate to engineering with the reqId, timestamp, endpoint called, and full request/response details.
  4. Ask engineering to look up the reqId in server logs to determine the server-side root cause.

Notes: If engineering cannot locate the reqId in logs, request additional timestamps and confirm the version/environment being used.

"We were not able to locate this request id in our logs, can we trouble you to provide a timestamp and which version are you currently using?" (ticket #87684)

Scenario: api-v2-endpoint-integration#sub-dust-threshold

Trigger: Customer receives ApiResponseError: sub-dust-threshold amount when sending a BTC transaction.

Signals: sub-dust-threshold, satoshis, minimum amount, BTC, ApiResponseError, 2730

Steps:

  1. Explain that the transaction amount is below the Bitcoin dust threshold.
  2. Inform the customer that the minimum amount for BTC is 2730 satoshis (0.00002730 BTC).
  3. Advise the customer to increase the send amount above this threshold.

Notes: This is a Bitcoin network constraint, not a BitGo-specific limit.

"From the error message, we can see you are trying to send 2000 satoshis. Please note the minimum amount for BTC is 2730 satoshis which is 0.00002730 BTC." (ticket #275773)

Scenario: api-v2-endpoint-integration#user-permissions-no-wallet-access

Trigger: Customer's API calls return empty results or errors because the access token user lacks per-wallet permissions on the enterprise.

Signals: empty response, no wallets, permissions, View all wallets, enterprise, List Enterprises, List Wallets

Steps:

  1. Check the admin tooling to confirm the user associated with the access token has permissions on the relevant enterprise(s) and wallet(s).
  2. If the user has "View all wallets" at the enterprise level but no per-wallet permissions, note that global enterprise-level GET calls may work but per-wallet granular calls will not return data.
  3. Advise the customer to start with the List Enterprises endpoint (https://developers.bitgo.com/api/enterprise.list) to retrieve Enterprise IDs, then pass those as query parameters to the wallet listing endpoint.
  4. If the user needs per-wallet access, an enterprise admin must grant appropriate permissions.

"I am showing the user does not have permissions on any wallets for these Enterprise. API calls looking to GET global wallet info from an Enterprise should work, but performing granular GET calls at per wallet level will not return information. Can you try passing the EnterpriseID as query parameter and let us know how the responses change?" (ticket #257461)

Scenario: api-v2-endpoint-integration#access-token-creation-for-third-party

Trigger: Customer asks how to generate API keys for third-party tax software (e.g., Koinly) or other integrations.

Signals: API key, access token, tax software, Koinly, third-party, Developer Options, generate

Steps:

  1. Explain that BitGo uses access tokens, not traditional API keys.
  2. Instruct the customer to create an access token from the web UI:
    • Click the Profile icon in the upper right of the platform and choose Settings.
    • Navigate to Developer Options.
    • Click Create New Access Token.
    • For tax/read-only purposes, select read-only permissions.
    • Click add access token to generate it.
  3. The customer can then provide or input this access token into the third-party software.
  4. Note that the access token will have equal to or fewer permissions than the user who created it.
  5. BitGo does not provide dedicated tax endpoints or integration support for specific third-party software. The customer should contact the third-party provider for their integration steps.

Notes: BitGo does not provide full integration solutions via email. Enterprise clients can engage a Solution Engineer for hands-on integration assistance. Non-enterprise users should be directed to https://www.bitgo.com/connect-with-us/ if they want dedicated integration support.

"An Access Token is needed so that 3rd-party tax software can interact via API with our platform. This can be created by choosing the Profile icon in the upper right of our platform and choosing settings. From there, choose Developer Options. From there, you can create an Access Token to provide or input into the tax software. The Access Token will equal to or less permissions than the person who created it. We do not have tax endpoints." (ticket #207367)

"In the Enterprise Settings menu, locate the Developer section. Click on Create New Access Token to start the process. You will be asked to specify the permissions for the API key. For tax purposes, you can select read-only access." (ticket #263984)

Scenario: api-v2-endpoint-integration#express-vs-sdk-endpoints

Trigger: Customer asks which endpoints are available on BitGo Express vs. SDK, or how they differ.

Signals: Express, SDK, local daemon, endpoints, integration, bitgo-express, npm

Steps:

  1. Explain that certain endpoints are called against the customer's local Express server instead of BitGo's hosted URLs. Express allows building, signing, and sending transactions locally without interacting with BitGo servers for any part of the process.
  2. Direct the customer to the full documentation: https://developers.bitgo.com/
  3. Non-Express endpoints can be tested via the API Explorer (beta): https://developers.bitgo.com/explorer
  4. Provide download links:

Notes: The API Explorer is a beta feature and not all endpoints are fully functional.

"Yes, certain endpoints are called against your Express Server instead of against our site URLs. This can allow your team to build, sign, and send transactions from API without need of interacting with Bitgo for any part of the process." (ticket #223903)

Scenario: api-v2-endpoint-integration#v1-to-v2-migration

Trigger: Customer requests migration of a v1 wallet to v2.

Signals: v1, v2, migration, migrate, legacy wallet

Steps:

  1. Inform the customer that BitGo is no longer completing migrations from v1 to v2.
  2. Advise the customer to create a new BTC wallet on the BitGo UI (which will be a v2 wallet) and transfer their funds from the old v1 wallet to the new v2 wallet.

Notes: This applies to legacy BTC v1 wallets only.

"Unfortunately, we are no longer completing migrations to v2. We would suggest that you create a new BTC wallet on our UI, which should be a v2 wallet, and move your funds there." (ticket #236795)

Scenario: api-v2-endpoint-integration#matic-to-pol-migration-errors

Trigger: Customer migrated from MATIC to POL coin ticker in API calls and receives 404 or 500 errors on production wallets, while test wallets worked fine.

Signals: MATIC, POL, 404, 500, coin ticker, migration, /api/v2/pol/, address, ApiResponseError

Steps:

  1. Request the full API request being made, including the request body and headers.
  2. Confirm whether the wallet was originally created under the matic coin type. If so, the wallet ID may not resolve under /api/v2/pol/.
  3. Escalate to engineering with the wallet IDs, the exact endpoints being called, and the full error responses to determine if backend migration of the wallet record from MATIC to POL is required.
  4. Confirm Express/SDK version, as older versions may not support the pol coin ticker.

Notes: Test wallets created fresh under pol may work correctly while production wallets originally created under matic may need backend migration or a different approach.

Scenario: api-v2-endpoint-integration#openapi-spec-compliance

Trigger: Customer reports that the openapi.json downloaded from developers.bitgo.com fails validation in tools like swagger.io when generating client libraries (e.g., C#).

Signals: openapi.json, OpenAPI, swagger, semantic error, structural error, C#, code generation, DELETE requestBody

Steps:

  1. Acknowledge the issue — known compliance problems with the published OpenAPI spec have been reported, including DELETE operations containing a requestBody (which violates the OpenAPI spec), undeclared path parameters, and invalid type values.
  2. Escalate to the engineering/developer-experience team as a spec compliance bug.
  3. Inform the customer that this has been reported and engineering is working on a fix.

Notes: This was previously escalated and resolved by engineering. If the issue recurs, re-escalate with the specific validation errors.

"Please close this first as engineering-dev has resolved this." (ticket #221027)

Scenario: api-v2-endpoint-integration#invalid-argument-productid

Trigger: Customer receives error "error":"backend:common:invalidArgument key=productID" when calling a pricing or product endpoint.

Signals: invalidArgument, productID, backend:common:invalidArgument, pricing, BTC

Steps:

  1. Request the following from the customer:
    • Full endpoint as called
    • Full payload
    • Email address of the user who created the authenticating access token
    • BitGo Express/SDK version being used
  2. Verify the productID parameter value being passed is valid and correctly formatted for the endpoint.
  3. If the parameter appears correct, escalate to engineering with the collected details and the reqId from the error response.

Scenario: api-v2-endpoint-integration#general-api-troubleshooting-info-request

Trigger: Customer reports vague API issues (e.g., "API not working," "no response," timeouts via Express) without providing specific error details.

Signals: API issues, no response, timeout, Express, not working, errors

Steps:

  1. Request the following standard diagnostic information:
    • Environment: Prod or Test
    • Enterprise Name and Enterprise ID
    • Wallet ID
    • User ID / email of access token creator
    • Error Message and requestId/reqId
    • UI or API
    • Full API endpoint exactly as called including BaseURL and HTTP method
    • Full payload omitting passwords
    • Full response
    • BitGo Express/SDK version
  2. If the customer reports Express timeouts, confirm the Express version and whether the Express server itself is healthy (check Express startup logs).
  3. Direct general API documentation questions to: https://developers.bitgo.com/
  4. For non-enterprise (free PayGo) accounts, note that they have very limited coin and token access, which may explain unexpected behavior.

"Please provide more details such as: Full endpoint as its being called including BaseURL and Method used, Full Payload being passed minus passwords, Full response including any errors and/or requestIDs" (ticket #214191)

"if you want a Solution Engineer who will assist on doing an on hand assistance with your integration these services are only available with our Business Enterprise clients. If you wish to become an enterprise client with us you may contact us at: https://www.bitgo.com/connect-with-us/" (ticket #194430)

Scenario: api-v2-endpoint-integration#api-token-permission-docs

Trigger: Customer asks for a definition of all API access token permissions and their scopes.

Signals: api access permissions, scope, definition, token permissions

Steps:

  1. Direct the customer to the access token documentation: https://developers.bitgo.com/reference/v2accesstokenadd
  2. This page describes the available permission scopes when creating an access token.

Scenario: api-v2-endpoint-integration#invite-user-api-error

Trigger: Customer receives an API error when attempting to add a new admin user to an enterprise or wallet.

Signals: add admin, invite user, API Error, new user, 2FA, KYC

Steps:

  1. This error typically means the user being invited has not yet logged in successfully or completed initial account setup.
  2. Instruct the customer to ensure the invited user logs in to BitGo and completes 2FA and KYC setup before the invitation is sent.
  3. Once the invited user's account is fully set up, retry the admin invitation.

"This error means that the user you are inviting to the wallet has not yet logged in successfully (usually a new user account that has not completed the setup), can you please make user hte user logs in successfully and completes the 2FA, kyc set up?" (ticket #232452)

Scenario: api-v2-endpoint-integration#fetch-whitelist-via-api

Trigger: Customer asks how to retrieve or list whitelisted addresses programmatically via the API, either for a specific wallet or across an entire enterprise.

Signals: fetch whitelist, list whitelist, programmatic, advancedWhitelist, expandAdvancedWhitelist, enterprise whitelist, whitelisted addresses API, walletId whitelist, enterpriseId whitelist, whitelist endpoint

Steps:

  1. To fetch the whitelist entries for a specific wallet, use the Get Wallet endpoint with the expandAdvancedWhitelist query parameter:
    GET /api/v2/{coin}/wallet/{walletId}?expandAdvancedWhitelist=true
Authorization: Bearer <accessToken>
    When expandAdvancedWhitelist=true, the response includes the wallet's whitelist entries from the advancedWhitelist rules, showing all whitelisted addresses, walletIds, and enterpriseIds for that wallet.
  2. To search or list whitelists across the whole enterprise (instead of one wallet at a time), use the aggregated enterprise whitelist endpoint:
    GET /api/v2/enterprise/{enterpriseId}/whitelists
Authorization: Bearer <accessToken>
    This returns a paginated list of whitelist entries (walletId, address, label, coin, etc.) across all wallets in the enterprise.
  3. Ensure the access token used has read permissions scoped to the relevant enterprise and wallets. Insufficient permissions can result in empty or error responses.

Notes: - The expandAdvancedWhitelist=true parameter is the per-wallet approach; the /enterprise/{enterpriseId}/whitelists endpoint is the enterprise-wide aggregated approach.

  • Both endpoints require a valid Bearer access token with appropriate read permissions.
  • Do not tell customers that no supported endpoint exists for listing whitelisted addresses programmatically — both endpoints above are confirmed and supported.

Related