MCP Server

Understanding error responses and how to handle them.

Error response format

All errors follow the JSON-RPC 2.0 error format:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32001,
    "message": "Unauthorized: Bearer token required"
  },
  "id": null
}

Protocol errors

These occur at the JSON-RPC level before reaching any tool.

Code	Name	Description
`-32600`	Invalid Request	Malformed JSON-RPC request (missing `jsonrpc`, `method`, etc.)
`-32601`	Method Not Found	Unknown method — only `initialize`, `tools/list`, `tools/call` are supported
`-32602`	Invalid Params	Missing required parameters (e.g. no `name` in `tools/call`)
`-32603`	Internal Error	Unexpected server-side error

Authentication errors

Code	Message	Cause	Solution
`-32001`	Unauthorized: Bearer token required	No `Authorization` header	Add `Authorization: Bearer dtk_live_...` header
`-32001`	Unauthorized: Invalid API key	Key doesn’t exist or is malformed	Check the key value and `dtk_live_` prefix
`-32001`	Unauthorized: API key has been revoked	Key was revoked by an admin	Generate a new API key
`-32001`	Forbidden: tool `<name>` requires `<required>` privilege	Key privilege too low	Ask a workspace admin to upgrade the key privilege, or use a different key

Tool errors

Tool-level errors are returned within the content field of a successful JSON-RPC response:

{
  "jsonrpc": "2.0",
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"success\": false, \"error\": \"invalid input parameters\", \"details\": \"...\"}"
    }]
  },
  "id": 1
}

Common tool errors

Error	Cause	Solution
`invalid input parameters`	Input validation failed (Zod schema)	Check the `details` field for specific validation errors
`Invalid filter value`	Enum filter value not recognized	Check response for `availableValues` to see valid options
`Invalid sourceContentObjectId`	Referenced content doesn’t exist	Verify content IDs with `get-contents` before using in drafts
`Company name already exists`	Duplicate company name in workspace	Use a unique name or search for the existing company first
`Email already exists`	Duplicate email for a person	Search for the existing contact first

Best practices

1. Always check success in tool responses

const result = JSON.parse(response.result.content[0].text);
if (!result.success) {
  console.error('Tool error:', result.error, result.details);
}

2. Handle pagination boundaries — Always check pagination.hasNext before requesting the next page. Requesting beyond the last page returns an empty result set. 3. Validate filter values first — When filtering by custom fields, query without filters first (small page size) to discover available values in the response metadata, then apply filters. 4. Retry on transient errors — For -32603 (Internal Error), implement exponential backoff retries. These are typically transient server issues. 5. Handle response size limits — Responses are limited to 90 KB. Use smaller page sizes and iterate through pages for large datasets.

Troubleshooting

Getting 401 Unauthorized with a valid key

Verify the Authorization header format: Bearer dtk_live_...
Ensure there are no extra spaces or line breaks in the key
Check if the key has been revoked in the Deeto admin console

Tool returns empty results

Check if filters are too restrictive — try without filters first
Use get-stats to verify data exists in the workspace
Confirm you’re using the correct userPrivileges value (reference vs prospect)

Response is truncated

Reduce pageSize to get smaller responses
Use specific fields to limit returned data
Check pagination.hasNext and request the next page

save-draft-content returns an error

Ensure publishedContent is provided and non-empty
Call get-content-instructions first for the correct schema
Verify all sourceContentObjectId references exist via get-contents
Check that name is at least 3 characters and unique per type in the conversation

Forbidden: insufficient privilege

The error message tells you exactly what’s needed: Forbidden: tool '<name>' requires '<required>' privilege but your API key has '<current>'. Ask a workspace Admin to generate a new key with the required privilege level.

Need help?

Contact your Deeto Customer Success Manager or email support@deeto.ai.

HubSpot

Salesforce

Other Integrations

MCP Server — Error Handling

Error response format

Protocol errors

Authentication errors

Tool errors

Common tool errors

Best practices

Troubleshooting

Need help?

​Error response format

​Protocol errors

​Authentication errors

​Tool errors

​Common tool errors

​Best practices

​Troubleshooting

​Need help?

Error response format

Protocol errors

Authentication errors

Tool errors

Common tool errors

Best practices

Troubleshooting

Need help?