Troubleshooting
Tool failures are structured rather than free-text, so an agent can react to them and you can diagnose them quickly.
Error categories
| Category | HTTP | Meaning |
|---|---|---|
validation | 400 | Arguments failed schema validation, an unknown field was sent, or no project was in context. |
not_found | 404 | Unknown tool, or the entity does not exist in the caller’s workspace. Cross-tenant ids always land here. |
forbidden | 403 | The caller’s workspace role does not hold the permission the tool requires. |
unsupported | 400 | The operation is not supported for this input, for example inspecting a non-glTF model file. |
too_large | 413 | The result or the per-reply tool budget was exhausted. Ask for a narrower slice. |
upstream | 502 | A dependency such as model-file storage failed. |
internal | 500 | Unexpected server error. |
conflict | 409 | A pending change went stale (the project changed since it was proposed) — re-run the tool. |
rate_limited | 429 | Per-connection or mutation rate limit hit — retry after the window resets. |
{
"success": false,
"tool": "get_project",
"error": {
"category": "not_found",
"message": "Project 8f14e45f-… was not found in this workspace."
}
}Common issues
The agent says it cannot find any projects
The token belongs to a different account than you expect, or you are acting in your personal workspace instead of a team workspace. Call get_current_workspace — it reports exactly which account and workspace the tools are running as.
Every call returns 402
The account’s trial or subscription has lapsed. Tool access resumes as soon as a plan is active; billing is checked on each request.
A tool returns "forbidden"
The workspace role does not hold the permission that tool requires. Check the permission badge in the Tool Reference and the seat’s role in Members.
The price the agent reports differs from Preview
Read the caveats array in the result. Number-input per-unit pricing, some bespoke pricing blocks, and conditional visibility are not applied by the server-side engine. Preview and the published Share view remain authoritative.
The agent cannot see a change I just made
Tools read saved data. Wait for autosave to complete or save explicitly, then ask again.
inspect_3d_model returns "unsupported"
Only glTF-family model files (.glb / .gltf) can be inspected. Other formats have no readable node structure.
The MCP client reports it cannot reach the server
The endpoint is live. Check (1) the token was pasted with the smcp_ prefix intact and has not been revoked or expired — see Dashboard → Integrations → AI Connections; (2) the workspace owner is on a Pro or Enterprise plan (or an active trial); (3) a corporate proxy or firewall allows POST requests to app.simplio3d.ai.
A write tool says the change is pending approval
That is by design and cannot be disabled: high-risk changes (pricing, SKUs, deletions, bulk edits) always require approval at Dashboard → Integrations → AI Connections before anything is modified. The agent should tell you a proposal is waiting — nothing has been applied until you approve it there.
The client shows "missing scope"
The connection was not granted the scope that tool requires. Re-authorize (OAuth) or create a new connection with the needed scopes — the full scope list is under Authentication, and each tool’s required scope is shown in the Tool Reference.