AI troubleshooting
Updated 2026-11-13
This page lists what can go wrong when an AI uses SpreadAPI, and what to do: the AI cannot connect, asks for a login, does not find or use the tool, sends wrong values, or is refused.
First: which address is the AI using?
https://spreadapi.io/mcp: a connection to your account. Managed on the AI agents (KI-Agenten) page.https://spreadapi.io/api/mcp/service/<service_id>: the MCP address of one service.https://spreadapi.io/d/<service_id>: the discovery address of one service.
The causes differ. See How AI assistants use a service.
The AI cannot connect to the account
| What you see | Cause | What to do |
|---|---|---|
| "This key is not valid (revoked or mistyped)." | the key was revoked, has passed its expiry date, was copied incompletely, or AI access is switched off | check the main switch and the expiry date under AI agents; otherwise create a new connection |
| "The sign-in has expired or was withdrawn. Sign in again." | the sign-in of Claude or ChatGPT is no longer valid, or the connection was revoked | sign in again from your AI client |
| "This needs a SpreadAPI connection" | the AI called without a key or sign-in | let the client sign in, or add the header Authorization: Bearer <your key> |
| The connection worked and stopped | expiry date reached, connection revoked, or AI access to this account switched off | open AI agents → Manage (Verwalten) and check |
A key must be sent complete and unchanged. It starts with spk_. If you no longer have it, revoke the connection and create a new one; a key is shown only once.
The sign-in page shows an error
| Message | What to do |
|---|---|
| "AI access is switched off for this account." | switch AI access to this account on under AI agents, then start the connection again |
| "This request has expired. Start the connection again in your AI client." | start again and confirm within a few minutes |
| "This account already has the most connections (25)." | revoke a connection under AI agents first |
| "The application that sent you here is not one SpreadAPI knows. Nothing was shared." | sign-in is offered for Claude, ChatGPT and Claude Code; connect any other client with a key |
| "The application asked to be answered at an address it has not registered. Nothing was shared." | start the connection again in your AI client |
| "That did not work. Start the connection again in your AI client." | start again; if it stays, contact support |
If the page asks you to log in first, that is expected: you confirm the connection as the signed-in account owner. Check the e-mail address on the page before you allow access.
The AI asks for a login on a service address
The service is protected by a token. The AI asks for a sign-in, and the person pastes a token you created under API → Access (API → Zugriff).
- The sign-in lasts 12 hours; after that the AI asks again.
- This sign-in is built for ChatGPT. For Claude use a connection to your account instead.
- If no sign-in should be needed, make the service public. See Tokens and access.
The service address does not answer
"Service not found or not published" means the service is a draft, was unpublished, or the id in the address is wrong. Publish the service and copy the address again from AI → Connect (KI → Verbinden). See Not found and unpublished.
The AI does not find the service or the tool
- Account connection, service missing in the list: the connection reaches only chosen services. Open the service, go to AI → Connect and tick the connection under AI connections, or change the connection to All services, including new ones under AI agents.
- Account connection, action refused: the level is too low. "may not create or change services" needs Edit (Bearbeiten); "may not publish services" needs Full access (Vollzugriff).
- The AI has the tool but does not use it: the description does not match the question. Fill What the service does, When the AI should use it and Example questions on AI → Definition, save and publish again. You can also tell the AI directly: "Use the SpreadAPI service for this."
- The AI still shows old texts or parameters: you changed the service but did not publish again, or the AI client read the tools earlier. Publish again, then reconnect the connector or start a new conversation.
The AI sends wrong values
| Symptom | Cause | What to do |
|---|---|---|
| A rate of 5% is calculated as 500% | the input is not marked as a percentage | format the cell as a percentage and publish again; see Percentages and formats |
| The AI sends a value that is refused | the value is outside the range or not one of the allowed values | nothing to fix: the answer names what is allowed and the AI corrects itself; widen the limits if the value should be allowed |
| The AI mixes up two inputs | names and descriptions are unclear | describe each input on AI → Definition; see Write good descriptions |
| The AI asks for values that have defaults | the input is required | make the input optional with a default on the Configuration (Konfiguration) tab |
| The result looks wrong | wrong input or a difference to Excel | compare the inputs echoed in the answer; see Wrong or old results |
The AI is told to stop
- "Monthly call limit reached": the account has used its calls for this month. Calls work again on the 1st of the next month (UTC) or right away on a larger plan. See Call limits.
- "Too many calls. Wait, then send the same call again.": an account connection makes at most 120 calls per minute. The AI should wait the seconds given and repeat the call.
- Publishing refused because of the plan: the plan does not allow another published service. See Published services limit.
Still stuck
Look at Recent activity (Letzte Aktivität) on the AI agents page: it shows what a connected AI tried and why a call was refused. For calls to one service, see the Usage (Nutzung) tab. If that does not explain it, contact support and include the address the AI uses, the message it got and the time.
For developers and agents
- Account address: a missing, invalid, expired or revoked credential answers HTTP 401 with a
WWW-Authenticateheader. Every other problem is a tool result withisError: trueanderror.code; see Agent errors. - Service MCP address: HTTP 401 "Authentication required" for a protected service without a valid token; HTTP 404 "Service not found or not published".
- Discovery address: HTTP 401, 404, 400 and 429 with
"success": falseand the reason inerror; see The discovery address. - An agent that is refused should pass the message on to its user and not try another way around it.
FAQ
Why can my AI not connect to SpreadAPI?
Most often the key is wrong, revoked or expired, the sign-in has ended, or AI access to this account is switched off. Check the connection under AI agents, then sign in again or create a new connection.
The AI says my key is not valid. What do I do?
Check that the whole key was copied, that the connection still exists and has not passed its expiry date, and that the main switch is on. If you no longer have the key, revoke the connection and create a new one.
Why does the AI keep asking me to sign in to a service?
The service is protected by a token, and the sign-in at a service address lasts 12 hours. For your own AI, use a connection to your account instead; it needs no token.
My AI does not see one of my services. Why?
The connection reaches only the services chosen for it. Tick the connection on the service's AI → Connect page, or set the connection to all services under AI agents → Manage.
The AI answers without calling my service. How do I fix that?
Make the description concrete and add example questions on AI → Definition, then save and publish again. You can also ask the AI explicitly to use the SpreadAPI service.
The AI sends 5 instead of 0.05 for a percentage. Is that a problem?
Not if the input is marked as a percentage: 5 and "5%" are then read as 5%. If the cell is not formatted as a percentage, 5 is taken as 500%, so format it and publish again.
I changed the service but the AI still uses the old version. Why?
Callers get the published version, so publish again after saving. If the AI client still shows old tools, reconnect it or start a new conversation.
The AI says the monthly call limit is reached. What now?
The account has used the calls its plan includes for this month. Calls work again on the 1st of the next month (UTC), or right away after an upgrade.
The consent page says the request has expired. What happened?
A sign-in request must be confirmed within a few minutes and can be decided only once. Start the connection again in your AI client.
Where can I see what my AI tried to do?
Under Recent activity on the AI agents page. Each line names the connection, the action, the service and, for a refused call, the reason.
As an agent, I get HTTP 401 from https://spreadapi.io/mcp. What should I do?
Start the sign-in if your client supports it; the WWW-Authenticate header points to it. Otherwise ask your user to create a connection at https://spreadapi.io/app/agents and give you the key, then send it as Authorization: Bearer <key>.