MCP errors

Understand Recipe errors, execution status, and recovery steps for people and agents.

An error means the tool did not return a successful result. It does not mean an empty wallet, zero balance, or clean air. Keep unavailable data separate from a measured zero.

This reference covers Recipe calls through the signed-in Bazantic MCP connection. The runner codes also apply to the paid Recipe MCP path. Individual Recipes can return their own provider errors inside output. Those errors have the contract of that Recipe.

Read the response

A Recipe failure has isError: true. The result carries the error in structuredContent.error and its text content. An HTTP 200 can carry this tool error. Check the tool result, not only the HTTP status.

For example:

{
  "isError": true,
  "structuredContent": {
    "error": {
      "code": "usage_unavailable",
      "message": "Bazantic could not check account usage. The Recipe did not run. This does not mean credits are exhausted.",
      "next_action": "Retry once after a short delay. If the error persists, contact Bazantic support with the tool name and time.",
      "retryable": true,
      "execution_started": false,
      "docs_url": "https://bazantic.com/docs/mcp-errors#usage-unavailable"
    }
  }
}

Field	Meaning
`code`	Stable identifier for program logic.
`message`	Explanation for the person who requested the result.
`next_action`	Recovery instruction for the person or agent.
`retryable`	A bounded retry can be appropriate under `next_action`. It does not promise recovery.
`retry_after_seconds`	Minimum delay before a retry after `rate_limited`.
`execution_started`	`false` confirms that the Recipe did not start. An absent field means unknown.
`docs_url`	Link to the explanation of the error.

The three errors below include these guidance fields. Older servers and runner errors can return only code. Treat absent guidance as unknown. Preserve unknown codes when you report an error. execution_started describes Recipe execution. It does not report usage counters or payment settlement.

Usage unavailable

Code: usage_unavailable.

Bazantic could not check account usage, so it refused the call before Recipe execution. The error does not establish a credit shortage, an expired connection, or a provider outage. It can affect unrelated Recipes because they share the same usage check.

Retry once after a short delay. If the error persists, stop. Contact Bazantic support with the tool name, error code, and request time with its time zone. Reconnect only when the server reports a separate authentication error.

Rate limited

Code: rate_limited.

The account reached a Recipe request limit. The Recipe did not run. The limit can apply to a short interval or a daily window. This error does not establish a wallet balance or a credit shortage.

Wait at least retry_after_seconds before one retry. Do not call another Recipe to bypass the account limit. If the field is absent, stop automatic retries. Ask the account owner to check the account limits.

Execution unavailable

Code: execution_unavailable.

Bazantic has no Recipe executor available for this call. The Recipe did not run. This response does not prove a provider failure.

Contact Bazantic support with the tool name and request time. Retry after service recovery.

Runner errors

These codes come from the Recipe runner. The response does not confirm whether each provider call completed. Check external results before you repeat a call that can change state or spend funds. Do not treat cancellation or a timeout as proof that an external action was undone.

Code	Meaning	Next action
`not_found`	The runner could not find a published Recipe.	Refresh the tool list. Select a published tool.
`invalid_input`	The input does not satisfy the Recipe schema.	Correct the input against the advertised schema.
`invalid_recipe`	The Recipe definition is invalid.	Report the error to the Recipe author.
`tool_unavailable`	A gateway tool is unavailable to the Recipe.	Ask the author to check the tool connection and publication.
`tool_failed`	A gateway tool call failed.	Check the external result before a retry. Report persistent failures.
`invalid_tool_call`	The model supplied input that the gateway tool does not accept.	Ask the author to check the Recipe and tool schema.
`model_failed`	The Recipe model call failed.	Check prior external results before a retry.
`no_tool_calls`	The model answered without the required tool evidence.	Treat the answer as unverified. Report the error to the author.
`step_limit_exceeded`	The run exceeded its step limit.	Report the error to the author. Check prior external results.
`time_limit_exceeded`	The run exceeded its time limit.	Check the external result before a retry.
`cancelled`	The request was cancelled.	Check the external result before you repeat the request.
`invalid_output`	The result does not satisfy the declared view contract.	Treat raw text output as unvalidated. Report the error to the author.
`internal_error`	The server could not complete the call because of an unexpected error.	Report the tool name and request time to support.

run_failed is an outcome in the Recipe metadata, not a specific error code. Use error.code to identify the runner failure.

Connection and protocol errors

Authentication and protocol errors can appear as a JSON-RPC error instead of a tool result. Read the application code in error.data.code and the explanation in error.message. Do not confuse the numeric JSON-RPC code with the application code.

For an authentication error, use the connection authorization flow.
For an authorization error, ask the account owner to check permissions and approved scopes.
For tool_not_found, refresh the tool list. A tool can be absent because of its publication state or your permissions.
For invalid_arguments, correct the arguments against the tool schema.
For an unknown error, preserve the original code and message. Stop automatic retries.

Rules for agents

Show the error explanation to the user.
Obey next_action and retryable when present.
Obey retry_after_seconds before a rate-limit retry.
Stop after one unsuccessful automatic retry.
Treat absent execution status as unknown.
Verify external results before you repeat a call with possible effects.
Identify any fallback source separately. Do not describe fallback data as a successful Bazantic result.
Report the tool name, code, request time, and time zone when support is necessary.

Do not include access tokens, API keys, or private provider responses in a support report.