Handling Errors

An error from a BundleUp request comes from one of two places:

BundleUp, before the request reached the provider: a bad key, an unknown connection, the rate limit, a failed token refresh.
The provider, passed through unchanged: a missing scope, a resource that doesn’t exist, the provider’s own rate limit.

They need different handling, so the first step is always telling them apart. Look at the body first. BundleUp’s own errors have a recognizable JSON body; everything else is the provider’s. Then act on the status.

BundleUp errors

Status	Code	What happened	What to do
`401`	—	API key missing or not recognized.	Check your configuration. Retrying won’t help.
`400`	`connection_invalid`	Connection ID missing, unknown, deleted, or from another workspace.	Stop using the connection. If it should exist, ask the user to reconnect.
`400`	`connection_refresh_failed`	The token expired and couldn’t be refreshed.	Retry later. If it keeps failing, the user probably revoked access. Ask them to reconnect.
`400`	`integration_not_found`	The connection’s integration was deleted.	The connection is unusable. Recreate the integration and have the user reconnect.
`400`	`mcp_not_supported`	MCP only: the provider has no MCP server.	Use the Proxy for this provider.
`429`	`rate_limit`	Over 100 requests in 60 s on this connection.	Wait for `Retry-After` (60 s), then slow down. See Rate limits.
`5xx`	—	An error inside BundleUp, or a failed token refresh the provider rejected.	Retry with backoff.

The Unified API reports the same situations with its own status codes and envelope (404 for an unknown connection or unsupported endpoint). See the errors reference.

Provider errors

Provider errors are passed through exactly as the provider sent them, so the provider’s documentation is the authority. Common cases:

Status	Usually means	What to do
`401`	The user revoked access, or the token is no longer valid.	Ask the user to reconnect.
`403`	The token lacks a scope, or the user lacks permission on the resource.	Check the integration’s scopes. The body often names what’s missing.
`404`	The resource doesn’t exist, or the user can’t see it.	Handle as not found.
`422` / `400`	The request body or parameters were invalid.	Fix the request.
`429`	The provider’s own rate limit.	Back off using the provider’s headers. Idempotent requests were already retried.
`408`, `502`, `503`, `504`	The provider timed out or was unavailable.	`GET`s were already retried. Retry later, or retry writes if they’re idempotent.

A pattern for your code

async function callProvider(connectionId: string, path: string) {
  const response = await client.proxy(connectionId).get(path);
  if (response.ok) return response.json();

  const contentType = response.headers.get('content-type') ?? '';
  const body = contentType.includes('json') ? await response.json() : await response.text();

  // BundleUp's own errors carry a "code"
  if (typeof body === 'object' && body?.code) {
    switch (body.code) {
      case 'connection_invalid':
      case 'integration_not_found':
        await markNeedsReconnect(connectionId);
        throw new NeedsReconnectError();
      case 'connection_refresh_failed':
        await recordRefreshFailure(connectionId); // reconnect after repeated failures
        throw new RetryLaterError();
      case 'rate_limit':
        throw new RetryLaterError(Number(response.headers.get('Retry-After') ?? 60));
    }
  }

  // Otherwise it's the provider's error
  if (response.status === 401) {
    await markNeedsReconnect(connectionId);
    throw new NeedsReconnectError();
  }
  throw new ProviderError(response.status, body);
}

Designing for reconnects

Every integration eventually loses access for some users: they leave the company, revoke your app, or change their password. Plan for it:

Store a status next to each connection in your database (active, needs_reconnect).
Set needs_reconnect on connection_invalid, on repeated connection_refresh_failed, or on a provider 401.
Show a clear “Reconnect” button that runs the authorization flow again.
After reconnecting, store the new connection ID and delete the old connection.

Get started

Concepts

Authentication

Integrations

Proxy

Unified API

MCP

Webhooks

Operations

Platform

BundleUp errors

Provider errors

A pattern for your code

Designing for reconnects

​BundleUp errors

​Provider errors

​A pattern for your code

​Designing for reconnects

BundleUp errors

Provider errors

A pattern for your code

Designing for reconnects