Agent errors

This page lists every error code an agent can get from the account address https://spreadapi.io/mcp: what it means, what the agent should do, and what it should tell its user.

How an error looks

Every answer of an action has the same form. A failure looks like this:

{ "ok": false,
  "action": "set_parameters",
  "error": {
    "code": "invalid_parameters",
    "message": "… Nothing was saved.",
    "problems": [ { "code": "…", "at": "…", "message": "Loan!B5 contains a formula. …" } ]
  } }

• error.code is one of the codes below. The codes are stable; decide by the code, not by the wording of the message.
• error.message says in plain words what is wrong. It is safe to pass on to the user.
• error.problems, when present, names each field or parameter with at and a message.
• error.options, when present, lists next calls that are ready to send (action, why, call).
• error.retry_after (for too_fast) is the number of seconds to wait.

Over MCP an error arrives in one of two ways:

• A missing or invalid connection answers HTTP 401 with a WWW-Authenticate header, before any action runs. This is what lets a client start its sign-in.
• Every other error is a normal tool result with isError: true; the envelope above is in structuredContent and, as text, in content.

All codes

Connection

Over MCP, key_required and key_invalid reach the client as the HTTP 401 answer described above, with the reason in the message.

Finding things

Input

Limits

Our side

Which action can return which code

Every action that needs a connection can return key_required, key_invalid, right_missing, invalid_input, too_fast and failed. In addition:

Typical cases

• `invalid_input` on `create_service`: send exactly one of sheets and xlsx_base64. A file that is too long for xlsx_base64 is refused the same way; send the cells as sheets instead.
• `invalid_input` on `update_service`: at least one field besides service_id is required.
• `invalid_input` on `read_cells`: the sheet or range could not be read; check the sheet name with describe_workbook.
• `invalid_parameters` on `set_parameters`: an input must be one cell without a formula; an output is a cell or range. Read the problems, correct the addresses and send all inputs and outputs again, because the call replaces all of them.
• `invalid_values` on `test_service` or `run_service`: each problem has at such as inputs.license_type and says what is allowed. A missing required input has the problem code missing.
• `not_published` on `run_service`: use test_service for a draft.

Warnings are not errors

A successful answer can carry warnings: things that worked but deserve a look, for example after set_parameters or publish_service. Read them and pass on what matters to the user.

For people: where refused calls show up

The AI agents (KI-Agenten) page lists refused calls under Recent activity (Letzte Aktivität) with the reason in words, for example "was refused: the connection may not do this" or "was refused: the service is a draft", and counts them under Refused calls (Abgelehnte Aufrufe). See The AI agents page.

Related: Rights and limits of a connection, AI troubleshooting, and for the errors of a service's own API Error reference.

For developers and agents

• The codes: key_required, key_invalid, right_missing, unknown_action, service_not_found, not_published, workbook_not_readable, invalid_input, invalid_workbook, invalid_parameters, invalid_values, publish_limit, call_limit_reached, workbook_too_large, too_fast, failed.
• what_can_you_do with guide: "errors" returns the same list as one text.
• HTTP 401 answers carry a JSON-RPC error with code -32001 and a message such as "This key is not valid (revoked or mistyped)." or "The sign-in has expired or was withdrawn. Sign in again."
• key_required carries connect_url, the page where the account owner creates a connection.
• Retry rules: retry unchanged after too_fast (after retry_after seconds) and after failed (later). Retry after a fix for the four invalid_… codes. Do not retry right_missing, publish_limit, call_limit_reached or workbook_not_readable.

FAQ

What error codes can the SpreadAPI agent connection return?

Sixteen: key_required, key_invalid, right_missing, unknown_action, service_not_found, not_published, workbook_not_readable, invalid_input, invalid_workbook, invalid_parameters, invalid_values, publish_limit, call_limit_reached, workbook_too_large, too_fast and failed.

As an agent, what do I do when I get right_missing?

Stop and tell your user that the connection may not do this and that the account owner can change it on the AI agents page. Do not try to reach the same result another way.

As an agent, what does service_not_found mean when the user says the service exists?

The service is not on your connection's list, belongs to another account, or the id is wrong. Call list_services; if it is missing there, ask the user to share the service with your connection.

As an agent, should I retry after too_fast?

Yes. Wait the number of seconds in retry_after, then send the same call again unchanged.

As an agent, should I retry after failed?

Try again later with the same request and do not change it, because the error is not caused by your input. If it stays, tell your user.

As an agent, what do I do at publish_limit?

Tell the user that the plan does not allow another published service and that they can unpublish another one or upgrade. Never unpublish anything on your own; the draft stays as it is.

As an agent, what do I do at call_limit_reached?

Do not retry. Tell the user that the month's calls are used up and that calls work again on the 1st of next month (UTC) or after an upgrade.

What does workbook_not_readable mean?

The workbook of the service was last saved in the editor, and the agent connection cannot read its cells. The service can still be run and its name, texts and token protection changed; cells and parameters are edited in the app.

What is the difference between invalid_input, invalid_parameters and invalid_values?

invalid_input means the arguments of the call do not fit the action. invalid_parameters means the chosen input or output cells do not fit the workbook, and invalid_values means input values for a calculation were rejected.

Why did my agent get an HTTP 401 instead of an error code?

A missing or invalid connection is answered with HTTP 401 before any action runs, so that an AI client can start its sign-in. All other errors come as a tool result with isError: true.

Where do I see why my agent was refused?

On the AI agents page under Recent activity: each refused call is listed with the connection, the time and the reason in words.

Was anything changed when a call fails?

No. A refused set_parameters saves nothing, a refused publish_service leaves the service as it was, and invalid_input means nothing was done.