MCP Error Reference

When a tool call fails, the SmartAlex MCP server returns an error in the tool response content. This page covers all error codes, their causes, and how to resolve them.

Two error layers: The SmartAlex API gateway returns HTTP status codes with JSON error bodies. The MCP server wraps these into plain-text error messages with actionable hints that your AI assistant sees directly. The examples below show both formats.

HTTP Status Codes

Status	Meaning	When it happens
200	Success	Request processed successfully
201	Created	Resource created (contacts, deals, webhooks, campaigns, agents)
400	Bad Request	Invalid parameters, missing required fields, or malformed UUID
401	Unauthorized	Missing or invalid API key / OAuth token
403	Forbidden	Valid auth but insufficient permissions for this resource
404	Not Found	Resource doesn’t exist or belongs to a different workspace
422	Validation Error	Request body failed schema validation (e.g. invalid field type or value)
429	Too Many Requests	Rate limit exceeded
500	Internal Error	Server-side error

Authentication Errors

401, Authorization required

Gateway response:

{
  "error": "Authorization required"
}

MCP tool response:

Failed to list contacts: Authorization required. Check your API key is valid and not expired.

Cause: No Authorization header was provided. Fix:

API key: Ensure SMARTALEX_API_KEY environment variable is set
OAuth: Reconnect the MCP server to trigger OAuth authentication
Cloud: Check that your AI client is sending the Bearer token

401, Invalid or expired token

{
  "error": "Invalid or expired token."
}

Cause: The API key or OAuth token is invalid, expired, or deactivated. Fix:

Regenerate your API key from the Developer Portal
For OAuth, re-authenticate by reconnecting the MCP server
Check that the key starts with sa_live_ (production) or sa_test_ (test)

Permission Errors

403, Insufficient permissions

{
  "error": "Insufficient permissions"
}

Cause: Your user account doesn’t have permission for this operation. SmartAlex uses role-based access control, your admin may have restricted access to certain features. Fix:

Ask your workspace admin to grant the required page permission
API keys inherit permissions from the user who created them

403, User principal required

{
  "error": "User principal required for this operation"
}

Cause: The request reached a permission-gated route but no user identity was provided. This can happen if an API key was created without a created_by user. Fix:

Regenerate the API key from a user account with appropriate permissions

403, API key does not have write permission

{
  "error": "API key does not have write permission"
}

Cause: The API key only has read permission but the operation requires write. Fix:

Generate a new API key with both read and write permissions from the Developer Portal

Validation Errors

400, Invalid parameters

{
  "error": "Invalid request body: first_name is required"
}

Cause: A required parameter is missing or a parameter has an invalid value. Common cases:

first_name is required for smartalex_create_contact
deal_name is required for smartalex_create_deal
url and event_types are required for smartalex_create_webhook
id must be a valid UUID for all get/update/delete operations
stage must be one of: lead, qualified, showing, offer, under_contract, closed_won, closed_lost

400, Invalid UUID

{
  "error": "Invalid UUID format"
}

Cause: An id parameter was provided but isn’t a valid UUID. Fix: UUIDs follow the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (e.g., a1b2c3d4-e5f6-7890-abcd-ef1234567890).

422, Validation error

Gateway response:

{
  "error": "name: String must contain at least 1 character(s)"
}

MCP tool response:

Failed to create campaign: name: String must contain at least 1 character(s). Check your input parameters for validation errors.

Cause: The request body failed schema validation. The field name and specific issue are included in the message. Fix: Check the field mentioned in the error against the Tools Reference for valid types and constraints.

Resource Errors

404, Not found

{
  "error": "Contact not found"
}

Cause: The requested resource doesn’t exist, or it belongs to a different workspace and is not accessible. Fix:

Verify the UUID is correct
Use the corresponding list_ tool to find valid IDs
Resources are workspace-scoped, you can only access your own data

Rate Limiting

429, Too many requests

{
  "error": "Too many requests",
  "message": "Rate limit exceeded. Please try again in 45 seconds.",
  "retryAfter": 45
}

Response headers:

Header	Description
`Retry-After`	Seconds to wait before retrying
`X-RateLimit-Limit`	Maximum requests per window
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Seconds until the rate limit window resets

Rate limits:

Transport	Limit	Keyed by
Cloud (authenticated)	100 requests/min	Workspace
Public (onboarding)	30 requests/min	IP address

Fix: Wait for the Retry-After duration and retry. Most AI clients handle 429 responses automatically with exponential backoff.

Server Errors

500, Internal server error

{
  "error": "Internal server error"
}

Cause: An unexpected error occurred on the server. Fix:

Retry the request, transient errors often resolve on the next attempt
If persistent, contact support at support@getsmartalex.com with the request details

MCP Protocol Errors

These errors come from the MCP SDK transport layer, not from SmartAlex tools.

406, Not Acceptable

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Not Acceptable: Client must accept both application/json and text/event-stream"
  }
}

Cause: The HTTP client isn’t sending the correct Accept headers for MCP Streamable HTTP transport. Fix: This typically means the client is making raw HTTP requests instead of using an MCP client library. Use a proper MCP client (Claude, Cursor, etc.) or set Accept: application/json, text/event-stream in your HTTP headers.

Gateway Errors

Gateway returned non-JSON

Gateway error: <!DOCTYPE html>...

Cause: The SmartAlex API gateway returned an HTML error page instead of JSON. Usually indicates the gateway is temporarily unavailable. Fix: Retry after a few seconds. If persistent, the gateway may be experiencing an outage.

No route found

{
  "error": "No route found for GET /unknown-path"
}

Cause: The MCP tool tried to call a gateway route that doesn’t exist. This indicates a version mismatch between the MCP server and the API gateway. Fix:

Local: Update to the latest version: npx @smartalex/mcp-server@latest
Cloud: This resolves automatically, contact support if it persists

Getting Started, Setup and troubleshooting
Tools Reference, All 28 tools with parameters
MCP Overview, Architecture and authentication

​MCP Error Reference

​HTTP Status Codes

​Authentication Errors

​401, Authorization required

​401, Invalid or expired token

​Permission Errors

​403, Insufficient permissions

​403, User principal required

​403, API key does not have write permission

​Validation Errors

​400, Invalid parameters

​400, Invalid UUID

​422, Validation error

​Resource Errors

​404, Not found

​Rate Limiting

​429, Too many requests

​Server Errors

​500, Internal server error

​MCP Protocol Errors

​406, Not Acceptable

​Gateway Errors

​Gateway returned non-JSON

​No route found

​Related Pages

MCP Error Reference

HTTP Status Codes

Authentication Errors

401, Authorization required

401, Invalid or expired token

Permission Errors

403, Insufficient permissions

403, User principal required

403, API key does not have write permission

Validation Errors

400, Invalid parameters

400, Invalid UUID

422, Validation error

Resource Errors

404, Not found

Rate Limiting

429, Too many requests

Server Errors

500, Internal server error

MCP Protocol Errors

406, Not Acceptable

Gateway Errors

Gateway returned non-JSON

No route found

Related Pages