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

# DialNexa MCP Responses And Errors

> Handle DialNexa MCP transport errors, tool failures, confirmation requirements, and safe retries.

DialNexa MCP errors fall into two categories: transport or authentication errors that prevent the MCP request from running, and tool-level errors returned inside a valid MCP response. Check the HTTP result first, then inspect `isError` and the response text.

## Successful MCP tool response

Every tool returns one text content block. The `text` field contains a JSON-encoded result:

```json theme={null}
{
  "content": [
    {
      "type": "text",
      "text": "{\"id\":\"agent_abc123\",\"title\":\"Support Agent\"}"
    }
  ]
}
```

Custom clients should parse `content[0].text` as JSON after confirming that the response is not marked as an error.

## Tool-level failure

When the MCP request is valid but the DialNexa operation fails, the server returns readable text and sets `isError: true`:

```json theme={null}
{
  "content": [
    {
      "type": "text",
      "text": "Could not get call call_abc123: no call found"
    }
  ],
  "isError": true
}
```

Treat the text as the operation-specific error message. Do not assume that every tool failure uses the same JSON shape inside `text`.

## Transport and authentication errors

| Result                     | Meaning                                                                                                         | Recovery                                                                                                                            |
| -------------------------- | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized`         | OAuth has not completed, the OAuth token is invalid, or the API key is missing, malformed, revoked, or invalid. | Let an OAuth-capable client follow the `WWW-Authenticate` discovery response, or replace the API key and keep the `Bearer ` prefix. |
| MCP initialization failure | The client did not complete the Streamable HTTP handshake or used an incompatible transport.                    | Confirm remote Streamable HTTP support and reconnect.                                                                               |
| Network timeout            | The client cannot determine whether the server completed the request.                                           | Use the retry rules below before sending another call.                                                                              |
| `isError: true`            | MCP transport succeeded, but the selected DialNexa tool failed.                                                 | Read the text block and correct the tool arguments or resource state.                                                               |

## Retry rules by safety level

Each tool reference page shows a safety label beside its title.

| Safety label  | Retry guidance                                                                           |
| ------------- | ---------------------------------------------------------------------------------------- |
| Read only     | Safe to retry after a transient timeout because the tool does not change workspace data. |
| Changes state | Read the affected resource first. Retry only when the intended change did not happen.    |
| Destructive   | Verify whether the target still exists or remains connected before retrying.             |
| Billable      | Check call, batch, or phone-number state before retrying to avoid duplicate spend.       |

MCP transport success does not guarantee operation success. Likewise, a client-side timeout does not prove that a state-changing operation failed.

## Confirmation errors

Some destructive and billable tools include a required `confirm` parameter. Set `confirm: true` only after the user approves the exact target and action in the current conversation.

If a tool rejects a missing confirmation:

1. Restate the resource and effect to the user.
2. Obtain explicit approval.
3. Re-read the target if it could have changed.
4. Call the tool once with `confirm: true`.

Do not cache approval for a different resource or a later unrelated action.

## Common tool failures

| Failure                     | Likely cause                                                         | Recovery                                                                                     |
| --------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Resource not found          | The ID is wrong, stale, or belongs to another workspace.             | Use the matching list tool and pass the prefixed ID exactly as returned.                     |
| Invalid arguments           | A required field, enum, nested object, or resource state is missing. | Compare the request with the tool's parameter table and description.                         |
| Insufficient wallet balance | A call, batch, or purchase requires more balance.                    | Recharge the workspace, then verify that the first attempt did not complete before retrying. |
| KYC requirement             | The workspace is not approved for the requested calling action.      | Complete KYC before placing outbound calls.                                                  |
| Confirmation required       | A protected operation did not receive approved `confirm: true`.      | Obtain explicit approval for that exact action.                                              |
| Result marked `truncated`   | A list tool reached its response cap.                                | Request another supported page or narrow the filters.                                        |

## Verify recovery

After correcting an error, use a read-only list or get tool to confirm the intended state. For calls and batches, store returned IDs and inspect their current status instead of inferring success from the absence of another error.

## Related pages

* [DialNexa MCP quickstart](/docs/mcp-tools/quickstart)
* [MCP server overview](/docs/mcp-tools/overview)
* [REST API errors](/docs/api-reference/errors)