DialNexa MCP Responses And Errors

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

Successful tools return the same JSON object in structuredContent and in a JSON-encoded text content block. Array payloads use an items property; scalar payloads use value:

{
  "content": [
    {
      "type": "text",
      "text": "{\"id\":\"agent_abc123\",\"title\":\"Support Agent\"}"
    }
  ],
  "structuredContent": {"id": "agent_abc123", "title": "Support Agent"}
}

After checking isError, read structuredContent or parse content[0].text as JSON. Each tool page includes its registered output schema. An empty schema permits any JSON value at that position; it does not promise a fixed object shape. Upload tools can also return host-only _meta for the upload interface.

Tool-level failure

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

{
  "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:

Restate the resource and effect to the user.
Obtain explicit approval.
Re-read the target if it could have changed.
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.

File Input And Protocol Errors

Send one JSON-RPC message per HTTP request. JSON-RPC arrays return 400 with code -32600; send separate requests instead. For file tools, supply exactly one source: host attachment, upload_id, or supported inline text/base64. Optional arguments sent as null are treated as omitted. An upload ID must match the workspace, resource, and upload kind and must still be valid. If the file is missing, oversized, expired, or the upload host is blocked, correct that issue before finalization. See MCP file uploads.

Start Here

Tool Reference

Successful MCP tool response

Tool-level failure

Transport and authentication errors

Retry rules by safety level

Confirmation errors

Common tool failures

Verify recovery

File Input And Protocol Errors

​Successful MCP tool response

​Tool-level failure

​Transport and authentication errors

​Retry rules by safety level

​Confirmation errors

​Common tool failures

​Verify recovery

​File Input And Protocol Errors

​Related pages

Successful MCP tool response

Tool-level failure

Transport and authentication errors

Retry rules by safety level

Confirmation errors

Common tool failures

Verify recovery

File Input And Protocol Errors

Related pages