Error Handling

Error format

All tool errors return the standard MCP error format:

{
  "content": [{ "type": "text", "text": "Error message here" }],
  "isError": true
}

The text field contains a JSON string with error details. Errors are actionable — they tell you what went wrong and suggest which tool to call next.

Common errors

Insufficient permissions

{
  "text": "Insufficient permissions: 'campaigns:write' scope is required to call campaignstack_create_campaign. Use campaignstack_whoami to check your current scopes."
}

Fix: Create a new API key with the required scope, or add the scope to your existing key.

Not found

{
  "text": "Campaign not found (id: abc123). Use campaignstack_list_campaigns to find valid IDs."
}

Fix: Use the suggested list tool to find valid IDs.

Validation error

{
  "text": "Invalid input: workspaceId is required"
}

Fix: Check the tool’s input schema and provide all required fields. All tools use .strict() validation — unknown fields are rejected.

Authentication errors (HTTP only)

Status	Message	Fix
401	”Authentication required. Provide a valid API key in the Authorization header: Bearer cs_…”	Add Authorization: Bearer cs_... header
401	”Invalid or revoked API key. Create a new key in Workspace Settings > API Keys.”	Key was revoked or doesn’t exist — create a new one

Cross-referencing pattern

CampaignStack errors consistently point to related tools. This helps AI agents self-correct:

• “Use campaignstack_list_campaigns to find valid IDs” — after a not-found error
• “Use campaignstack_whoami to check your current scopes” — after a permission error
• Tool descriptions reference related tools: “Use the returned campaignId values with campaignstack_get_campaign, campaignstack_list_workflows, or campaignstack_list_lead_lists.”

This pattern enables agents to recover from errors without human intervention.

Input validation

All tools enforce strict input validation via Zod schemas:

• Required fields — missing required fields return clear error messages
• Type checking — wrong types (string where number expected) are rejected
• Range validation — numeric limits (e.g., limit must be 1-100) are enforced
• Unknown fields — extra fields not in the schema are rejected (.strict() mode)