Which status codes does the REST API return?
These are the failures you can meet, with a typical message for each:
| Status | When it happens | Example message |
|---|---|---|
| 400 | Invalid JSON, a field that fails validation, an unknown setting or the 100-source limit | Set approved to true or false. |
| 401 | A missing, malformed, unknown or revoked token | Invalid or revoked workspace token. |
| 403 | Sending humanNumber, turning on human handover, an early release, before that agent’s team number is verified in the dashboard, or using a token on a dashboard-only route, such as phone verification | Verify your team phone number in Settings before enabling handover. |
| 404 | An unknown endpoint, or a source, conversation or GitHub file that isn’t found | Source not found. |
| 409 | A settings update that collided with another, or a test email with no address to go to | Settings changed at the same time. Try again. |
| 413 | A request body over 150,000 bytes | Request is too large. |
| 429 | A second test email within a minute | Wait a minute before sending another test email. |
| 500 | An unexpected server error | Something went wrong. Please try again. |
| 502 | GitHub couldn’t return a file | GitHub could not sync this document. Check permissions and try again. |
| 503 | Website import, which is switched off, or email or storage that isn’t available | Website import is unavailable on this deployment. Add reviewed sales notes instead. |
Which errors should you retry?
Retry only what can succeed unchanged:
- 409 from a settings update: send the same request again. It only changes the fields you send.
- 500 and 502: retry after a pause, waiting longer each time.
- 503: retry later, except for website import, which stays switched off.
- 429: wait a minute.
- 400, 401, 403, 404 and 413: fix the request first, because sending it again gives the same answer. The exception is a GitHub import that returns 400 with a short technical message after a slow reply from GitHub, which you can retry once.
- POST /api/manage/sources isn’t idempotent. If one times out, check the sources list before you send it again, or you may add a duplicate. GitHub imports and approvals are safe to repeat.
How does the MCP server report errors?
A tool that fails returns a normal JSON-RPC result with isError set to true and a plain-language message as its text, such as “Source not found in this workspace.” Your MCP client passes it to the model, which can correct the call.
A request the server can’t accept gets a JSON-RPC error object instead: -32001 with HTTP 401 for a token problem, or 403 for another website’s Origin header, and other codes for protocol mistakes. The MCP server reference lists every code.
What limits apply?
The management API doesn’t meter ordinary requests today, but limits may be added during the pilot, so poll every few minutes rather than in a tight loop. There’s no uptime commitment or SLA.
| Limit | Value |
|---|---|
| Free conversations | The first 50 per workspace, one time only, shared by support, sales and dashboard tests. Paid calls aren’t available yet, so new calls are refused once they’re used. |
| Call length | 10 minutes, then the call ends |
| Calls at once | 3 starting or in progress per workspace, across both agents |
| New calls | 12 a minute per workspace |
| Knowledge sources | 100 per workspace |
| Source text | 50,000 characters, with a title of up to 140 |
| GitHub import | One .md, .mdx or .txt file per request, up to 50,000 characters |
| Allowed origins | 10 per agent |
| Agent text | Product name 80 characters, agent name 60, greeting 500, instructions 4,000 and button label 30 |
| Request body | 150,000 bytes |
| Visitor’s topic | 1 to 1,000 characters |
| Conversations in the workspace response | The latest 100 |
| Test email | One a minute |