Transport errors
Returned as JSON-RPC errors on the HTTP response:
Every error body carries
error.data.correlationId. Quote it when reporting a problem — it is the handle to the server-side log line, and the body deliberately never contains the underlying exception message. The same id is returned as the x-request-id header on every response from doola’s API servers.
A 403 Forbidden is returned when the request carries an Origin header naming an origin this server does not accept.
Auth challenges
A401 Unauthorized (with a WWW-Authenticate challenge) is returned when the bearer token is missing, malformed, or inactive. Re-authenticate via the OAuth flow.
Tool-level failures
Validation rejections, missing state, precondition gates, and backend errors are not JSON-RPC errors. Per the MCP spec they surface inside the successful response’sresult.content. Inspect result.isError and the embedded error / code / message.
For the formation tools, most error responses carry the same steering fields as success. Follow nextAction, filling the placeholders in nextActionInput, rather than retrying the same call. A validation rejection without nextAction means fix the input as message describes and retry. When save_company_details fails part way, saved lists the sections it wrote before the failure:
”No active session”
The most common runtime failure is a missing or expired identity — typically an expired token. Recover by re-authenticating (the bearer is the source of identity), then callget_company_onboarding_status to confirm where to resume. Don’t redo steps the customer already completed.