Error Handling

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

Error format

{
  "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)
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.

{
  "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:

Google

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

Getting Started

Concepts

Sources

Error Handling

Error Handling

Error format

Error codes

MCP tool errors vs HTTP errors

HTTP-level errors

Tool-level errors

Source-specific errors

Meta

LinkedIn

Google

​Error Handling

​Error format

​Error codes

​MCP tool errors vs HTTP errors

​HTTP-level errors

​Tool-level errors

​Source-specific errors

​Meta

​LinkedIn

​Google

Error Handling

Error format

Error codes

MCP tool errors vs HTTP errors

HTTP-level errors

Tool-level errors

Source-specific errors

Meta

LinkedIn

Google