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

# Error Handling

> Error codes, classes, and resolution guidance

# Error Handling

All errors follow a consistent format with an error message and code.

## Error format

```json theme={null}
{
  "error": "Missing or invalid API key",
  "code": "UNAUTHORIZED"
}
```

## Error codes

| HTTP Status | Code             | Error Class                | Description                            | Resolution                                                    |
| ----------- | ---------------- | -------------------------- | -------------------------------------- | ------------------------------------------------------------- |
| 401         | `UNAUTHORIZED`   | `UnauthorizedError`        | Missing or invalid API key             | Check your `Authorization: Bearer` header                     |
| 401         | `UNAUTHORIZED`   | `NoCredentialsError`       | No credentials found in API key        | Ensure channels are connected in workspace settings           |
| 403         | `FORBIDDEN`      | `ForbiddenError`           | Access denied                          | Check API key permissions                                     |
| 403         | `FORBIDDEN`      | `ChannelNotConnectedError` | Channel not connected for this API key | Connect the channel in workspace settings                     |
| 404         | `NOT_FOUND`      | `NotFoundError`            | Route not found                        | Check the endpoint URL                                        |
| 429         | `RATE_LIMITED`   | `RateLimitError`           | Rate limit exceeded                    | Wait and retry with backoff (see [Rate Limits](/rate-limits)) |
| 500         | `INTERNAL_ERROR` | `InternalError`            | Internal server error                  | Retry; contact support if persistent                          |

## MCP tool errors vs HTTP errors

There are two levels of errors:

### HTTP-level errors

Returned as standard HTTP responses (status code + JSON body). These happen before a tool executes — auth failures, rate limits, missing routes.

### Tool-level errors

Returned inside a successful HTTP 200 response with `isError: true` in the MCP result. These happen during tool execution — invalid parameters, upstream API failures, etc.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Error listing campaigns: Invalid access token"
      }
    ],
    "isError": true
  }
}
```

## Source-specific errors

Each ad platform can return specific errors that are caught and wrapped:

### Meta

* **`MetaApiProcessingError`** — Graph API returned an error (invalid params, permissions, etc.)
* **Rate limiting** — Meta's Business Use Case rate limiting triggers automatic retries (3x with backoff)

### LinkedIn

* **RestLi errors** — LinkedIn's API uses a specific error format that is normalized
* **`serviceErrorCode`** — LinkedIn-specific error codes are included in the error message

### Google

* **`ChannelNotConnectedError`** — Google credentials not found in API key
* **Cross-source errors** — `/drive/upload-to-meta` requires both Google and Meta channels connected