Errors and limits

Handle Embedded MCP HTTP errors, tool errors, rate limits, expired result sets, and safe retries.

Check where the error occurred before retrying. HTTP errors happen before a tool runs. Tool errors return an MCP result with isError: true.

HTTP errors

Status	Code	Next step
401	No code	Check the API key and service health. A key lookup failure can also return 401. Do not create another end user.
403	`EMBEDDED_NOT_ENABLED`	Enable MindCloud Embedded for the organization.
403	`EMBEDDED_MCP_NOT_ENABLED`	Turn on the Embedded MCP server switch.
403	`COMPANY_SCOPE_MISMATCH`	Remove a conflicting `X-Company-Id` header.
403	`API_KEY_ACCESS_DENIED`	Use a key with the required access level.
404	`END_USER_NOT_FOUND`	Check the stored ID and key's organization before creating a new end user.
429	`RATE_LIMITED`	Wait before another request.
421 or 503	Region or authorization unavailable	Use the correct region or retry after service recovery.
503	`END_USER_LOOKUP_UNAVAILABLE`	Retry after the end-user lookup service recovers.
500	JSON-RPC `-32603`	Retry after MCP server recovery.

GET and DELETE on the MCP URL return 405. Send POST requests. The endpoint allows 600 requests per minute per API key.

Tool errors

{"success":false,"error":{"code":"NOT_CONNECTED","message":"...","nextStep":"get-connect-url","retryable":false}}

Code	Next step
`APP_NOT_FOUND`	Search apps again.
`ACTION_NOT_FOUND`	Search that app's actions again.
`NOT_CONNECTED`	Create a connect link for this end user.
`CONNECTION_INVALID`	Pass the named `connectionId` to `get-connect-url` to repair it.
`CONNECTION_CHOICE_REQUIRED`	Ask the user to choose a connection; pass its ID as `connectionRef`.
`CONNECTION_NOT_FOUND`	List the end user's connections again.
`RESULT_SET_NOT_FOUND`	Run the original action again if the result expired.
`VALIDATION_ERROR`	Match arguments and query controls to the action schema.
`MCP_ACTION_EXECUTE_FAILED`	Inspect the provider status and message in the error detail.
`RATE_LIMITED`	Wait before creating another connect link.
`TEMPORARILY_UNAVAILABLE`	Retry after the dependency recovers.

An idempotencyKey reused with different input can return MCP_IDEMPOTENCY_CONFLICT. A call still running with that key can return MCP_IDEMPOTENCY_LOCKED. Keep the same key only when retrying the same write.

Input schema errors and unknown tool names can return plain text without an error code. Read the tool's input schema and correct the call. Do not treat a missing connection as an empty response from a failed dependency.