> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.deeto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server — Error Handling

> Error codes, troubleshooting guides, and best practices for the Deeto MCP Server.

Understanding error responses and how to handle them.

***

## Error response format

All errors follow the JSON-RPC 2.0 error format:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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**

```javascript theme={null}
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

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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`)
  </Accordion>

  <Accordion title="Response is truncated">
    * Reduce `pageSize` to get smaller responses
    * Use specific `fields` to limit returned data
    * Check `pagination.hasNext` and request the next page
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

***

## Need help?

Contact your Deeto Customer Success Manager or email [support@deeto.ai](mailto:support@deeto.ai).