Skip to main content

​
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 StatusCodeError ClassDescriptionResolution
401UNAUTHORIZEDUnauthorizedErrorMissing or invalid API keyCheck your Authorization: Bearer header
401UNAUTHORIZEDNoCredentialsErrorNo credentials found in API keyEnsure channels are connected in workspace settings
403FORBIDDENForbiddenErrorAccess deniedCheck API key permissions
403FORBIDDENChannelNotConnectedErrorChannel not connected for this API keyConnect the channel in workspace settings
404NOT_FOUNDNotFoundErrorRoute not foundCheck the endpoint URL
429RATE_LIMITEDRateLimitErrorRate limit exceededWait and retry with backoff (see Rate Limits)
500INTERNAL_ERRORInternalErrorInternal server errorRetry; 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:

​
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