Errors

Errors from the hosted MCP server come back in one of three ways, depending on where they happen:

Where	What you get	Examples
Before MCP runs	An HTTP status with a small JSON body	Not signed in (401), too many requests (429)
In the MCP request	A JSON-RPC error object	Unknown tool, unknown method
Inside a tool	A normal result with isError: true	Invalid category, transaction not found, read-only connection

Most errors an AI agent sees are tool errors. They’re written so a model can read them, fix the call and try again, or explain the problem to the person.

Tool Errors

When a tool fails, the response is still a successful JSON-RPC result, with isError set to true. The text content and structuredContent hold the same JSON: error is what went wrong and status is the HTTP status Maple Budget’s API answered with.

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "isError": true,
    "content": [
      { "type": "text", "text": "{\"error\": {\"errors\": \"Category must be an integer between 1 and 30.\"}, \"status\": 400}" }
    ],
    "structuredContent": {
      "error": { "errors": "Category must be an integer between 1 and 30." },
      "status": 400
    }
  }
}

Most messages arrive as {"errors": "<message>"} inside error. A few, like the read-only message below, are a plain string with no status.

Common Errors

Message	Status	Cause	What to do
This Connection Can Only Read. Reconnect To Allow Changes.		The connection is Read Only and the tool changes data	Tell the person. They can disconnect in AI Apps and connect again with Read And Make Changes.
Category must be an integer between 1 and 30.	400	category isn’t one of the 30 category ids	Use an id from Categories.
Invalid tag IDs or tags do not match transaction category.	400	A tag id doesn’t exist or belongs to another category	Get tag ids from get_on_launch_data and use tags from the same category.
Month needs to be between 1 and 12 and year needs to be between 2000 and 2050.	400	month or year is out of range	Send month 1 to 12 and a four-digit year.
Month And Year Must Be Integers.	400	month or year isn’t a whole number	Send numbers, like month: 10, year: 2026.
Invalid Date Format. Use 'YYYY-MM-DD'.	400	A date isn’t YYYY-MM-DD	Reformat the date, like 2026-10-31.
Invalid amount spent. Must be a decimal number.	400	amount_spent isn’t a number	Send a decimal string, like "42.50" (negative for income).
Title Must Be Under 100 Characters.	400	title is over 100 characters (subtitle has the same limit)	Shorten it.
Transaction Not Found.	404	The transaction id doesn’t exist or isn’t the person’s	Look the id up again with get_transactions.
Bad Arguments: …		A required argument is missing or an unknown one was sent	Check the tool’s parameters in the Tool Reference.
Something Went Wrong Running This Tool.		An unexpected server error	Try once more. If it keeps happening, tell the person and tell us with send_feedback.
Bad Arguments: message is required: …		send_feedback was called with an empty message	Say what you were trying to do and what was missing or wrong.
That's a lot of feedback for one day. …	429	More than 50 send_feedback reports from this person today	Nothing was sent. Tell the person, and try again tomorrow.

Messages are passed through from Maple Budget’s API as written, so their capitalization varies.

Tell Us

If an error doesn’t make sense, a tool you need doesn’t exist, or a result doesn’t match the person’s accounts, tell us with send_feedback. Pick a kind (missing_tool, wrong_result, error, confusing or other), say what you were trying to do and what would have helped, and add the tool and an example if you have them. Every connection can send it, Read Only too, and it doesn’t change the person’s data. It comes back with “Sent to the Maple Budget team. Thanks.” Don’t include card numbers, passwords or other secrets.

Request Errors

These come back before any tool runs.

Status	Body	Cause	What to do
401	{"error": "unauthorized", "error_description": "Sign In To Maple Budget."}	No token, or the token expired or was revoked	MCP apps refresh or sign in again on their own. With an API key, check it hasn’t been revoked.
403	{"error": "origin_not_allowed"}	A browser page on another site called the server	Call it from your app or server, not from a web page.
429	{"error": "rate_limited", "error_description": "Too Many Requests."}	More than 5,000 requests this hour for this connection or key	Wait the number of seconds in Retry-After.
400	JSON-RPC error -32700 Parse Error	The body isn’t valid JSON	Send one JSON-RPC message as JSON.
400	JSON-RPC error -32600 Batches Aren't Supported	The body is a JSON array	Send one message per request.
405		A GET request	Use POST. There’s no standing event stream.

The 401 response includes WWW-Authenticate: Bearer resource_metadata="…", scope="read write", which is how MCP apps find the sign-in page. See Authentication.

JSON-RPC Errors

Code	Message	Cause
-32602	Unknown Tool: <name>	No tool has that name. Call tools/list for the current list.
-32602	arguments Must Be An Object	arguments was sent as something other than an object
-32601	Method Not Found: <method>	The server supports initialize, ping, tools/list and tools/call
-32600	Invalid Request	The message isn’t valid JSON-RPC 2.0

Local Server Errors

The local server calls Maple Budget’s API with your API key. When the API answers with an error, the tool fails with the HTTP status and the address it called, for example:

Error executing tool add_transaction: 400 Client Error: Bad Request for url: https://api.maplebudget.com/api/transactions/add/

The API’s own message isn’t included, so check the arguments against the table above. A 401 Client Error: Unauthorized means the key in MAPLE_BUDGET_API_KEY is missing, mistyped or revoked: create a new one in AI Apps.