MCP errors and what to do

Every failed Motorical tool call returns a structured result with isError: true and this body. Branch on code, never on the message text, which can change.

Field	Meaning
code	A stable string. Compare it exactly: the codes below are case-sensitive.
error	A plain message. It never contains an internal route.
status	The HTTP status behind the failure, or null.
hint	The next move, in one sentence.
details	The upstream body when there is one, for example missingScopes, retryAfterSeconds or nextAction.
candidates	Only on MOTOR_BLOCK_REQUIRED: the Motor Blocks you can pass, each as { id, name }.

Two families of codes exist, because some are assigned by Motorical's authentication layer (lowercase, passed through unchanged) and the rest by the tool layer (uppercase).

Connection and permission codes (lowercase)

Code	Status	Meaning	What to do
insufficient_scope	403	The connection does not hold a permission the tool needs. details.missingScopes names it.	Call motorical_whoami to see what is held. Tell the person which permission to add (Motorical dashboard, Settings, API access), then start a new chat or reconnect. Do not retry unchanged.
missing_scope	403	Same cause, from the REST API rather than the MCP layer.	As above.
authorization_revoked	401	The person revoked this connection. It takes effect on the next call.	Stop and ask the person to reconnect the connector.
invalid_access_token, access_token_required, invalid_token_type	401	The token is expired, missing or the wrong kind. Clients normally refresh and retry on their own.	If it persists, ask the person to reconnect.
grant_mismatch, delegation_grant_mismatch, wrong_resource	403	The token was issued for another server or grant.	Reconnect to the server whose address you are using.
motor_block_not_authorized, workspace_not_authorized	403	The id you passed is not covered by this connection.	Use an id from a list tool; if the person wants it covered, they add it under the connection's settings.
motor_block_not_found, motor_block_not_owned	403	The Motor Block does not exist for this account.	List blocks with motorical_list_motor_blocks and use one of those ids.
account_suspended	403	The account is suspended.	Tell the person; nothing you do will fix it.
subscription_required	403	The feature needs a plan.	Only the person can subscribe. Read live plans from GET https://motorical.com/api/billing/plans.
catalog_outdated, coverage_unavailable	503	Motorical could not decide safely and refused (it fails closed).	Wait a moment and retry once; if it persists, tell the person Motorical is having trouble.
sandbox_outbound_locked, sandbox_recipient_denied	403	A sandbox account tried to email a recipient who is not unlocked.	Unlock the recipient with motorical_free_recipient_add, then send again.

Tool-layer codes (uppercase)

Code	Status	Meaning	What to do
MOTOR_BLOCK_REQUIRED	none	The connection covers several Motor Blocks and the call named none.	Call again with motorBlockId set to one of candidates. With exactly one granted block you never need to pass it.
NO_MOTOR_BLOCKS	none	The connection covers no Motor Block yet.	Ask the person to reconnect and approve access to their Motor Blocks.
NOT_AVAILABLE_OVER_OAUTH	none	The action exists only in the dashboard.	Ask the person to do it there.
NOT_FOUND	404	The id does not exist in this scope.	Re-check it with a list tool; it may belong to another block or account.
VALIDATION_FAILED	400, 422	An input is wrong. The message names the field.	Fix that field and call again.
UNAUTHENTICATED	401	The connection is no longer signed in.	Ask the person to reconnect.
FORBIDDEN	403	Refused for a reason without a more specific code.	Call motorical_whoami, then explain what is missing.
PLAN_REQUIRED	402	The plan does not include this.	Only the person can change plan.
CONFLICT	409	The state changed or the action clashes with it.	Re-read the current state, then decide again.
RATE_LIMITED	429	Too many calls or sends. details.retryAfterSeconds and details.nextAction say how to proceed.	Wait, or call motorical_get_account_rate_limits, then retry.
UPSTREAM_ERROR	5xx	Motorical had a problem.	Retry once after a short wait; otherwise tell the person.
TOOL_ERROR	none	Anything else.	Read error; correct the call if it names a problem.

Confirmation requests

Some tools change or delete things and ask the person to confirm. A client that supports it shows the person a prompt; a result with input_required means the call is waiting for that answer and has not run. Pass confirm: true only after the person said yes.

Communications codes

Marketing tools return their own domain codes (for example AMBIGUOUS_TEMPLATE and LIST_CARD_INVALID), each with a hint. They are described beside the tools on the Communications tools page and in the Communications guide.