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

# Troubleshooting

> Common issues when calling the Lofty MCP server, and how to resolve them.

## "No operation with id '...'"

`describe_api` or `invoke_api` was called with an `operationId` that doesn't exist. Operation ids are stable but not guessable from the resource name alone — call [`search_apis`](/mcp/tools-reference#search_apis) first rather than constructing one. For example, deleting a lead is `lead_trash`, not `lead_delete`.

## search\_apis didn't return the operation I expected

Ranking is a weighted keyword match over each operation's real documentation, not semantic search — it has no synonym matching or stemming beyond exact and prefix matches. The right operation reliably appears within the top few results, but isn't always first.

* Read the summaries of results 2–5 before concluding nothing fits.
* Try naming the record type (lead, transaction, task, call, email) together with the action (list, get, create, update).
* If you already know the exact `operationId` from an earlier `search_apis` call in the same session, you can call `describe_api` or `invoke_api` directly without searching again.

## I'm not sure whether to use the v1 or v2 version of an operation

Several resources — tasks, calendar, communication, transactions — have both a `/v1.0` and a `/v2.0` operation for what looks like the same action. They aren't interchangeable, and neither version is universally preferred:

* v2 task and calendar operations unify tasks and appointments under one id namespace and support fields v1 doesn't.
* v1 remains the only version for some actions.

Read both candidates' `describe_api` output rather than assuming the higher version number is always correct.

## A field name isn't in describe\_api's schema

If a field you expect isn't in an operation's static schema, it may be a team-defined custom field — these are configured per team and can't appear in any static schema. Call [`list_custom_fields`](/mcp/tools-reference#list_custom_fields) before assuming the field doesn't exist or guessing an id for it.

## invoke\_api returned a 401 or 403

The credential is missing, invalid, expired, or the underlying application isn't authorized for that operation:

| Status                | Likely cause                                                                                                                                                             |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `401`                 | Missing, malformed, or expired credential. Confirm you're sending `Authorization: Bearer <token>` — see [Authentication](/mcp/authentication).                           |
| `403` (code `200100`) | An OAuth 2.0 app calling an operation it hasn't been granted. Grant the scope in the [Developer Portal](https://api.lofty.com/vendor/frontend/static/index.html#/login). |
| `403` (other)         | The authenticated user doesn't have permission for this record or action — the same restriction would apply calling the REST API directly, or using the CRM itself.      |

## invoke\_api returned a 404 for a record I expect to exist

This is usually a real, correct answer rather than an auth problem — for example `lead_get` returns `404` when the `leadId` doesn't exist *for the authenticated caller's team*, which includes leads that exist but belong to a different account. Double-check the id and which credential you're using.

## The response was truncated

A very large response is cut and prefixed with a `NOTE: ...` line explaining what was trimmed and how to get the rest (for example, by narrowing the query or paging). Read that line — don't treat a truncated list as the complete result.

## Still stuck?

Check [Error Codes](/authentication/error-codes) for the full list of API error codes, or see the [API Reference](/api-reference/leads/overview) for the same operations documented as plain REST calls.