Transport errors
Returned as JSON-RPC errors on the HTTP response:| Code | HTTP | Meaning |
|---|---|---|
-32600 | 400 | Missing Mcp-Session-Id header on a non-initialize request. Echo the header from initialize. |
-32603 | 500 | Internal error. The body’s error.message includes the underlying cause. |
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 advance_company_onboarding, error responses carry the same steering fields as success — follow nextAction and nextActionInput rather than retrying the same call:
code | Meaning |
|---|---|
INVALID_INPUT | Missing or malformed action / params. |
UNKNOWN_ACTION | The action isn’t one of the supported values. |
PRECONDITIONS_NOT_MET | Earlier steps are incomplete. missing lists them in flow order; nextActionInput is the step to do first. |
READINESS_CHECK_FAILED | A transient backend issue while verifying state. Retry in ~10 seconds. |
FILING_FAILED | The submission couldn’t be filed. The message explains what to retry. |
”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.