> ## 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.

# Errors

> Every error BundleUp returns, by API, and how to tell them apart from provider errors.

Errors come from two sources:

1. **BundleUp**, in the formats below.
2. **The provider**, passed through unchanged on the Proxy, MCP and (for failed upstream calls) the Unified API.

For how to handle each case, see [Handling errors](/docs/guides/operations/error-handling).

## Proxy and MCP errors

```json theme={null}
{ "status": 400, "code": "connection_invalid", "message": "Missing or invalid connection ID" }
```

| Status | `code` | Message | Cause |
| - | - | - | - |
| `401` | — | `Not authorized` | API key missing or not recognized. The body has `status` and `message` only. |
| `400` | `connection_invalid` | `Missing or invalid connection ID` | No connection ID, an unknown one, or one from another workspace. |
| `400` | `connection_refresh_failed` | `Failed to refresh connection` | The token expired and the connection has no way to refresh it. |
| `400` | `integration_not_found` | `Integration not found for connection` | The connection’s integration was deleted. |
| `400` | `mcp_not_supported` | `MCP is not supported for this integration` | MCP only. The provider has no MCP server. |
| `429` | `rate_limit` | `Too many requests` | Over 100 requests in 60 seconds on this connection. `Retry-After: 60`. |

The Proxy can also return these with a short plain-text body:

| Status | Body | Cause |
| - | - | - |
| `408` | `Request timed out` | The provider didn’t respond within 20 s (10 s on retries). |
| `502` | `Error fetching proxied request` | BundleUp couldn’t reach the provider. |

A `5xx` with no body usually means a token refresh was rejected by the provider, or an internal error. Retry with backoff.

## Unified API errors

```json theme={null}
{
  "success": false,
  "errors": [{ "code": 1000, "message": "Not Authorized" }]
}
```

| Status | Cause |
| - | - |
| `400` | A required header or parameter is missing or invalid. `errors` describes which. |
| `401` | The API key isn’t recognized. Code `1000`. |
| `404` | The connection doesn’t exist or isn’t in this workspace; its token couldn’t be refreshed; its integration was deleted; or its provider doesn’t support this endpoint. |
| `429` | Over the connection’s rate limit. Code `1001`. |
| `500` | An internal error. |

If the provider returns an error, the Unified API passes the **provider’s** response through instead of this envelope.

## Auth API errors

`POST https://auth.bundleup.io/connection` and the Platform API share this format:

```json theme={null}
{
  "success": false,
  "message": "Invalid request",
  "errors": { "code": ["Invalid or expired authorization code"] }
}
```

| Status | `message` | Cause |
| - | - | - |
| `400` | `Invalid request` | Validation failed. `errors` maps each field to its messages. |
| `401` | `Not authorized` | API key missing or not recognized. |
| `404` | `Not found` | Platform API only. The resource doesn’t exist in this workspace. |

Errors in the browser part of the flow (`/authorize`) are shown as a page to the user, or sent to your `redirect_uri` as `error` and `error_description` query parameters. See [Connecting user accounts](/docs/guides/auth/authorization-flow#step-3-handle-the-redirect).

## Codes in request logs

Request logs use some extra codes to describe what happened. See [Logs](/docs/guides/operations/logs#error-codes-in-logs).


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