# Troubleshooting

> Fix common Digital Calculator MCP server errors by symptom: HTTP 429 rate limits, rejected keys, 413 and 415 requests, INPUT_VALIDATION, unknown tools, rule_year 2027, reports and connection problems.

**URL**: https://www.digitalcalculator.info/mcp/troubleshooting/  
**Last Updated**: 2026-11-13

Find what you are seeing, then the cause and the fix. Every error code is listed once, with its HTTP status, in the [API reference’s errors table](https://www.digitalcalculator.info/mcp/api-reference/#http-status-mapping); this page is the “what do I do about it” side.

Two shapes of error come back from `/mcp`, and it helps to know which you have. A **tool-level error** (a bad argument, a rule the server cannot answer) is HTTP 200 with `result.isError: true` and an `{"error":{"code":...}}` object in `content[0].text`. A **JSON-RPC error** (a rate limit, a rejected key, a request the server cannot read) has a numeric `error.code` and usually a non-200 status. The REST routes return one `{"error":{...}}` object either way ([details](https://www.digitalcalculator.info/mcp/api-reference/#errors)).

## Rate limits (HTTP 429)

### 429 with a JSON-RPC error `-32000` (REST: `RATE_LIMIT`)

**Cause.** Your own allowance is used up. `error.data.scope` says which one: `window` is the 5-minute window, `daily` is the UTC day. The allowance is per IP address with no key, shared across Claude’s connectors for calls that come through them, and per key with a key ([the numbers](https://www.digitalcalculator.info/mcp/pricing/)). Only `tools/call` is counted: connecting, listing tools and reading resources never use it up.

**Fix.** Wait, then retry. Which header tells you how long depends on the limit:

-   **A 5-minute window**, with or without a key: wait the `Retry-After` seconds.
-   **The daily allowance with no key**: `Retry-After` counts down to UTC midnight.
-   **A key’s daily allowance**: there is no `Retry-After`; `X-Quota-Reset` gives UTC midnight as Unix seconds.

If you hit the daily allowance regularly, a [key](https://www.digitalcalculator.info/mcp/keys/) gives you one of your own. Reference: [errors table](https://www.digitalcalculator.info/mcp/api-reference/#http-status-mapping), [headers](https://www.digitalcalculator.info/mcp/api-reference/#headers).

### 429 with only `{"message":"Too Many Requests"}`

**Cause.** The shared limit on the whole API (about 100 requests a minute, shared by every caller), not your allowance. That is why it has no JSON-RPC body and no rate-limit headers.

**Fix.** Back off for a few seconds and retry, with growing gaps if it repeats. A key does not raise this limit ([rate limits](https://www.digitalcalculator.info/mcp/api-reference/#rate-limits)).

## Keys

### 401 with `-32001` (REST: `UNAUTHORIZED`)

**Cause.** You sent an `Authorization` header and the key in it is malformed, unknown, revoked or expired. `error.data.reason` says which: `invalid_token`, `token_revoked` or `token_expired`. The server never falls back to the anonymous allowance when a key is refused.

**Fix.** Check the header is exactly `Authorization: Bearer <key>`, with the whole key and no quotes or line breaks. A free key expires one year after it was created: [create a new one](https://www.digitalcalculator.info/mcp/keys/#replace-it). For a paid key, email us for a replacement. To use the anonymous allowance instead, remove the header. Reference: [errors table](https://www.digitalcalculator.info/mcp/api-reference/#http-status-mapping).

### My key is not being used

**Cause.** The client is not sending it. The npm package `@markcolabs/mcp` never sends a key, and Claude’s custom connectors cannot send this server’s key. Without rate-limit headers on a successful answer, the call was anonymous: every keyed answer carries them.

**Fix.** Connect over HTTP from a client that can send an `Authorization` header ([which clients can](https://www.digitalcalculator.info/mcp/keys/#clients)).

## Requests the server refuses

### 413 “Request body too large”

**Cause.** The request body is over 4 KB (4,096 bytes), on `/mcp` or the REST route. On `/mcp` it is a JSON-RPC error `-32600` with `"id": null`; on REST it is `INPUT_VALIDATION`.

**Fix.** Send less: one JSON-RPC message per request (batches are not served), and no fields the tool does not take. A large `money_flow_map` budget is the call most likely to reach the limit; shorten its item names or group items. Reference: [body size and JSON](https://www.digitalcalculator.info/mcp/api-reference/#body-limit).

### 400 with `-32700` (REST: “Body is not valid JSON”)

**Cause.** The body did not parse as JSON. From a terminal this is usually shell quoting: Windows `cmd` and PowerShell treat single quotes differently from bash.

**Fix.** Put the JSON in a file and send it with `curl -d @body.json`, or check the quoting for your shell.

### 415 with `-32600` and `unsupported_media_type`

**Cause.** The request has a body but does not declare `Content-Type: application/json`. Some HTTP tools default to form encoding.

**Fix.** Add `-H 'Content-Type: application/json'` (a `charset` parameter is fine). Reference: [headers](https://www.digitalcalculator.info/mcp/api-reference/#headers).

### 403 with `origin_not_allowed`

**Cause.** The request carries an `Origin` header from a site other than `https://www.digitalcalculator.info`, which is what a browser sends from a web page.

**Fix.** Call the server from your backend, a command-line tool or an MCP client, not from browser code. Those leave `Origin` out. Reference: [errors table](https://www.digitalcalculator.info/mcp/api-reference/#http-status-mapping).

## Input errors

### `INPUT_VALIDATION` naming a camelCase argument

**Cause.** Arguments are snake\_case. An unknown argument is refused rather than ignored, so that a misspelling cannot quietly change an answer, and the message proposes the closest accepted name: `"unknown argument 'annualReturnPercent' — did you mean 'annual_return_percent'?"`. `field` names the argument. Four tools (`mortgage_monthly_payment`, `loan_monthly_payment`, `paycheck_net_pay`, `emergency_fund_recommendation`) still accept their older camelCase spellings; every other tool does not. Sending both spellings of one argument with different values is also refused.

**Fix.** Use the name the message suggests, or the names in `tools/list`. The one place camelCase is right is the `input` object of [`generate_report`](https://www.digitalcalculator.info/mcp/reports/#call). Other `INPUT_VALIDATION` messages say what is wrong in plain words: `"<field> is required"`, `"<field> must be a number"`, or the accepted range. Reference: [unknown arguments](https://www.digitalcalculator.info/mcp/api-reference/#strict-arguments), [older names](https://www.digitalcalculator.info/mcp/api-reference/#legacy-rest-aliases).

### `Unknown tool: <name>`

**Cause.** The tool name is not one the server has. It is an `INPUT_VALIDATION` error. Tool names are snake\_case (`mortgage_monthly_payment`); the dot-separated names of the old 0.2.x package (`dc.calculator.mortgage.monthlyPayment`) were retired.

**Fix.** Call `tools/list` and use a name from it. If the missing tool is `generate_report`, see [below](https://www.digitalcalculator.info/mcp/troubleshooting/#report-auth). Reference: [the tools](https://www.digitalcalculator.info/mcp/api-reference/#tool-index).

### `BUSINESS_RULE` on a `rule_year: 2027` call

**Cause.** The call asked for the 2027 rules, and the answer needs a 2027 figure the server does not hold yet. The message names the missing figures, and `field` is `rule_year`.

**Fix.** Use `rule_year: 2026`, or leave `rule_year` out (2026 is the default), or ask again once the figures are published. Reference: [errors table](https://www.digitalcalculator.info/mcp/api-reference/#http-status-mapping).

## Reports

### `authentication_required` from `generate_report`, or the tool is missing

**Cause.** `generate_report` needs a paid `dc_bearer_` key. With no key or a free `dc_pub_` key it is left out of `tools/list`, and calling it anyway returns `authentication_required`.

**Fix.** Send a paid key ([getting one](https://www.digitalcalculator.info/mcp/keys/#paid-key), [using reports](https://www.digitalcalculator.info/mcp/reports/)).

### `report_quota_exceeded`, `rate_limited` or `REPORT_UNAVAILABLE`

**Cause.** `report_quota_exceeded`: the key’s daily report quota is used up. `rate_limited`: the key’s 5-minute window, which reports share with calculator calls, is full. `REPORT_UNAVAILABLE`: the `tool` you named has no report.

**Fix.** Retry after UTC midnight for the daily quota, or once the 5-minute window resets. For `REPORT_UNAVAILABLE`, use one of the aliases the message lists. Reference: [`generate_report` errors](https://www.digitalcalculator.info/mcp/api-reference/#generate-report-errors).

## Connecting

### The client cannot connect, or the server shows no tools

**Cause.** Usually the URL or the transport. The server answers only a `POST` to exactly `https://mcp.digitalcalculator.info/mcp`, over the Streamable HTTP transport. Anything else, including a `GET`, the URL without `/mcp`, or a client set to the older SSE transport, gets 404 Not Found.

**Fix.**

-   Check the URL ends in `/mcp` and starts with `https://mcp.` (`api.digitalcalculator.info` is the REST host and has no `/mcp`).
-   Choose the “HTTP” or “Streamable HTTP” transport, not SSE. If your client speaks only stdio, use the [npm package](https://www.digitalcalculator.info/mcp/quickstart/#option-3).
-   In claude.ai or Claude Desktop, check the connector is switched on in the conversation’s tools menu. If you filled in the connector’s authentication fields, remove it and add it again with them blank: this server has no sign-in to complete.
-   Test the endpoint on its own with `curl` and a `tools/list` request ([example](https://www.digitalcalculator.info/mcp/quickstart/#option-4)), or with [MCP Inspector](https://www.digitalcalculator.info/mcp/quickstart/#option-2).

Client-by-client steps are in the [quickstart](https://www.digitalcalculator.info/mcp/quickstart/#option-1).

### The npm package will not start

**Cause.** `@markcolabs/mcp` needs Node.js 18 or later. On an older Node, `npx` warns about an unsupported engine and the package may fail to start.

**Fix.** Run `node --version` and upgrade to Node.js 18 or later. If your client launches the package itself, make sure it finds that Node, not an older one on another path.

### “Request timed out after 30s” from the npm package

**Cause.** The package gives each request 30 seconds to reach the hosted server and answer. A timeout means the request did not get through in time, usually a network problem between you and the server.

**Fix.** Retry. If it keeps happening, try the endpoint directly with `curl` to see whether the network or the server is the problem, and check the [status page](https://www.digitalcalculator.info/mcp/status/).

## Still stuck?

Email [admin@markcolabs.com](mailto:admin@markcolabs.com?subject=MCP%20Server%20Problem) with the request you sent (with any key removed), the full response, and the time. Please report every `INTERNAL` error (HTTP 500, `-32603` on `/mcp`). The [FAQ](https://www.digitalcalculator.info/mcp/faq/) covers questions that are not errors.

---

*Markdown copy of [https://www.digitalcalculator.info/mcp/troubleshooting/](https://www.digitalcalculator.info/mcp/troubleshooting/). For tool definitions, the hosted server's tools/list is authoritative.*
