> ## Documentation Index
> Fetch the complete documentation index at: https://bundleup.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting & FAQ

> Common problems and their fixes, plus answers to frequent questions.

## Connecting accounts

<AccordionGroup>
  <Accordion title="BundleUp shows “Invalid client_id or integration_id.”">
    The `client_id` doesn’t match your workspace’s (copy it from **Auth** in the dashboard), or `integration_id` doesn’t match an integration’s **identifier**. Identifiers are case-sensitive. Also check you’re using the client ID from the same workspace as the integration.
  </Accordion>

  <Accordion title="BundleUp shows “redirect_uri is not registered for this workspace.”">
    The `redirect_uri` must match an entry under **Auth → Redirect URIs** exactly: scheme (`http` vs `https`), host, port, path and trailing slash all count.
  </Accordion>

  <Accordion title="The provider says the redirect URI or callback URL doesn’t match.">
    That’s the provider’s check, not BundleUp’s. Your OAuth app at the provider must list `https://auth.bundleup.io/callback` as a callback or redirect URL.
  </Accordion>

  <Accordion title="I’m redirected back with error=token_error.">
    The provider rejected the token exchange. Usually the client ID or secret on the integration is wrong, or the secret was regenerated at the provider without updating BundleUp.
  </Accordion>

  <Accordion title="Exchanging the code fails with “Invalid or expired authorization code.”">
    The code is more than 5 minutes old, was already exchanged, the `redirect_uri` in the exchange isn’t exactly the one used to start the flow, or the API key is from a different workspace. Codes are single use: a page refresh that re-runs your callback will fail the second time.
  </Accordion>

  <Accordion title="The user took a long time and the flow failed.">
    A flow has to be completed within 10 minutes of starting. Send the user through it again.
  </Accordion>
</AccordionGroup>

## Making requests

<AccordionGroup>
  <Accordion title="401 Not authorized.">
    The `Authorization` header is missing or the API key is wrong. It must be `Bearer YOUR_API_KEY`. If you rotated the key, the old value stopped working immediately.
  </Accordion>

  <Accordion title="400 connection_invalid (or 404 on the Unified API).">
    The connection ID is missing, has a typo, was deleted, or belongs to a different workspace than the API key. A common cause is using a development connection ID with a production key.
  </Accordion>

  <Accordion title="400 connection_refresh_failed.">
    The access token expired and couldn’t be refreshed. If it happens once, retry later. If it keeps happening, the user has probably revoked access; ask them to reconnect. See [Connection lifecycle](/docs/guides/auth/connection-lifecycle#when-a-refresh-fails).
  </Accordion>

  <Accordion title="The provider returns 404 for a path that exists.">
    Check the path against the provider’s **base URL** (shown on its page at [bundleup.io/integrations](https://www.bundleup.io/integrations)). If the base already contains a segment like `/api` or `/v4`, don’t repeat it in your path.
  </Accordion>

  <Accordion title="The provider returns 403.">
    Usually a missing scope. Add it to the integration, then have the user reconnect: existing connections don’t gain new scopes. See [Choosing scopes](/docs/guides/integrations/scopes).
  </Accordion>

  <Accordion title="429 with code rate_limit.">
    The connection made more than 100 requests in 60 seconds. Wait 60 seconds and spread your requests out. See [Rate limits](/docs/guides/proxy/rate-limits).
  </Accordion>

  <Accordion title="408 Request timed out.">
    The provider didn’t answer within 20 seconds (10 seconds on retries). For large exports, use paginated or asynchronous endpoints.
  </Accordion>

  <Accordion title="A POST failed and wasn’t retried.">
    By design. Only `GET`, `HEAD` and `OPTIONS` are retried. See [Retries](/docs/guides/proxy/retries#retrying-writes-yourself).
  </Accordion>

  <Accordion title="Unified API returns 404 for a valid connection.">
    The connection’s provider doesn’t support that endpoint. Each provider’s page at [bundleup.io/integrations](https://www.bundleup.io/integrations) lists its Unified API endpoints. Use the [Proxy](/docs/guides/proxy/overview) for anything else.
  </Accordion>
</AccordionGroup>

## MCP

<AccordionGroup>
  <Accordion title="400 mcp_not_supported.">
    The provider doesn’t run an MCP server BundleUp can use. Use the [Proxy](/docs/guides/proxy/overview), or give your agent your own tools that call it.
  </Accordion>

  <Accordion title="My MCP client can’t connect, or asks to sign in with OAuth.">
    `mcp.bundleup.io` uses static credentials, not OAuth discovery. Use a client that lets you set headers or a single bearer token, or bridge with `mcp-remote`. See [Using MCP clients](/docs/guides/mcp/clients#developer-tools).
  </Accordion>

  <Accordion title="Fewer tools appear than I expected.">
    The provider shows tools based on the connection’s scopes. Add scopes to the integration and have the user reconnect.
  </Accordion>

  <Accordion title="Two servers expose tools with the same name.">
    Tool names come from providers and aren’t prefixed. Give each server a distinct label (model-hosted MCP) or prefix tool names yourself. See [Agents for many users](/docs/guides/mcp/multi-tenant-agents).
  </Accordion>
</AccordionGroup>

## Webhooks

<AccordionGroup>
  <Accordion title="Signature verification always fails.">
    Hash the **raw** body, not re-serialized JSON, and use that webhook’s own signing secret. See [Verifying signatures](/docs/guides/webhooks/verifying#troubleshooting).
  </Accordion>

  <Accordion title="I missed an event.">
    Deliveries are attempted once, with a 3-second timeout, and not resent. Respond quickly and reconcile periodically with `GET /v1/connections`.
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Can I use BundleUp without my own OAuth app?">
    No. You always bring your own OAuth app credentials for each provider. That keeps your brand on the consent screen and your app’s limits and approvals separate from anyone else’s.
  </Accordion>

  <Accordion title="Can I move existing connections into BundleUp?">
    Yes. Create connections from tokens you already hold with `POST /v1/connections`, passing the integration ID, access token, and optionally the refresh token, expiry and external ID. Use the same OAuth app in the integration as the one that issued the tokens.
  </Accordion>

  <Accordion title="Does BundleUp store my users’ data?">
    BundleUp stores the encrypted tokens and connection metadata. It doesn’t store request or response bodies. See [Security](/docs/platform/security).
  </Accordion>

  <Accordion title="Do I pay per connection or per integration?">
    No. You pay for requests. See [Pricing](/docs/platform/pricing).
  </Accordion>

  <Accordion title="Which providers are supported?">
    See [bundleup.io/integrations](https://www.bundleup.io/integrations), which also shows Unified API and MCP support for each.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.