# Errors

> What a failed request or tool call returns from the Maple Budget MCP server, the messages you'll see most, and what to do about each.

Maple Budget docs. Hosted MCP server: `https://api.maplebudget.com/mcp` (Streamable HTTP, OAuth sign-in). Web page: https://maplebudget.com/docs/errors/ · Index of all pages: https://maplebudget.com/llms.txt

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.

```json
{
  "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](https://maplebudget.com/docs/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](https://maplebudget.com/docs/mcp-tools). |
| `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](https://maplebudget.com/docs/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](https://maplebudget.com/docs/mcp-local) 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:

```text
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](https://app.maplebudget.com/menu/api-keys).