# API errors now say which plan you need

October 2026 · API

Plan and quota refusals add machine-readable fields, Pro responses say when the history window cut data, MCP get_metric takes a resolution, and the price WebSocket explains a plan refusal.

## What's new

Every API refusal keeps its HTTP status and its `error` text. Plan and quota refusals now add fields beside `error`, so a client can branch on `code` instead of matching text:

```json
{"error":"resolution 10m requires an Advanced or enterprise token","code":"plan_required","required_plan":"advanced","current_plan":"pro","feature":"finer_resolution","upgrade_url":"https://newhedge.io/pricing#advanced"}
```

- `code` is `plan_required`, `subscription_inactive` or `quota_exceeded`.
- `required_plan`, `current_plan`, `feature` and `upgrade_url` say what was refused and where to upgrade.
- `quota_exceeded` also carries `limit` and `resets_at`, the first day of the next month at 00:00 UTC.
- A real token on a free or lapsed account still gets `Invalid token`, now with `code: subscription_inactive`. A token that matches no account is unchanged.

Pro tokens receive a rolling one-year window of history. When the window removes points, the metrics, price history, candles and company responses now carry `X-Newhedge-History-Truncated: true`, `X-Newhedge-History-Window-Days`, `X-Newhedge-Plan` and `X-Newhedge-Upgrade-Url`. The body is unchanged. MCP tools add a `meta` object beside the data in the same case.

A few charts also return only their most recent points to Pro tokens. When that limit cuts a metrics response, it now carries `X-Newhedge-Points-Limited: true`, `X-Newhedge-Points-Limit` (the number of points returned), `X-Newhedge-Plan` and `X-Newhedge-Upgrade-Url`. The body is unchanged.

MCP `get_metric` and `get_latest_value` accept an optional `resolution`, with the same rules and the same quota as the REST endpoint. Without it, nothing changes.

The price WebSocket now tells a paid token without the Enterprise feature why it was rejected, and tells an unknown `source` the valid sources, instead of closing the subscription with no message.

## Related

- [Errors and plan limits](https://docs.newhedge.io/api#errors)
- [AI agents and MCP](https://docs.newhedge.io/api/agents)