Troubleshooting
Common errors when connecting or creating cases, and the current limitations of the beta.
Connecting fails
| Symptom | Meaning | Fix |
|---|---|---|
| Sign-in window says the request expired | The consent link is valid for 10 minutes | Start the connection again from the assistant |
401 with invalid-token | The key behind the connection does not exist | Reconnect |
401 with key-revoked / key-expired | The connection's key was deleted in the dashboard, or aged out | Reconnect, or create a new key (Authorization) |
403 with company-disabled | The company account is disabled | Contact support |
405 Method not allowed | The client tried the older SSE transport | Use a client that supports Streamable HTTP |
| Client can't authenticate at all | The client supports neither OAuth nor custom headers | Switch clients, or bridge with mcp-remote (Connect) |
A connection is just an API key (see Connect) — deleting it in the dashboard takes effect on the assistant's next request, so an assistant that suddenly reports authentication errors was likely disconnected there.
key-has-no-user
Only affects API-key connections. Creating a case acts on behalf of a person, and some keys (typically partner-issued ones) have no person behind them. Use a key created from the dashboard by the user the assistant should act as — or connect with OAuth, where this cannot happen.
"The case was rejected"
The assistant sent something the API refused. All problems come back at once, each naming the field. The usual causes:
- An open case with no recipients or no documents — add them, or ask for a
draft. - An SMS recipient without a phone number.
- A document with more than one source — exactly one of a link, file contents, or a library id.
- A file over 20 MB.
- A misspelled or unknown field — the schema rejects unknown keys rather than ignoring them.
- For a case from a library template: a tag the template does not have, a value for an automatic field (company name, date, sender), a wrong type, a dropdown value that is not one of the options, or a required field left empty. The assistant should re-read the fields with
get_documentand ask you for what is missing.
The assistant sees the same explanation you do, so "fix it and try again" usually works — but see the next section first.
Duplicate cases
There is no idempotency key yet: retrying a request that actually succeeded creates a second case and can email your signers twice.
After any error, timeout, or "did that work?" moment — check the dashboard before asking the assistant again. If a duplicate slipped through, delete it in the dashboard.
Beta limitations
- Four tools. Creating cases, and listing, reading and creating cases from your document library. No listing, updating or deleting of cases over MCP yet (the REST API has more), and no uploading to the library — new templates are added in the dashboard.
- No idempotency key. See above.
- No rate limiting on the MCP endpoint yet. Don't treat that as a licence to hammer it; a limit is coming.
- Scopes are not enforced. Every connection currently has full access to its company. Grants are already recorded with
cases:write; the document tools will requiredocuments:readonce enforcement arrives, and today's connections keep working. publicUrls(REST query flag) is not available over MCP.