> How many calculations each Check Take Home Pay plan includes a month and how many calls a second, what counts, what happens at the limit, and the headers that show where you are.

Web version: https://checktakehomepay.co.uk/docs/limits · Last updated: 2026-10-09

# Limits

Each plan sets how many calculations it includes a month and how many calls a second each key can make. Every plan has every endpoint and every tax year.

## By plan

| Plan | Included a month | Beyond that | Calls a second, per key |
| --- | --- | --- | --- |
| **Free** | 100 calculations a month | Stops until next month (402, with an upgrade link) | 5 a second |
| **Pro** | 5,000 calculations a month | £4 per 1,000 more | 20 a second |
| **Scale** | 50,000 calculations a month | £2 per 1,000 more | 50 a second |
| **Enterprise** | Your volume | Agreed with you | Agreed, with an SLA |

Months are calendar months in UTC: the free allowance starts again on the 1st. Prices and plans are on [pricing](https://checktakehomepay.co.uk/pricing).

## What counts

-   One successful call (a 200) to an endpoint that needs a key is one calculation, whichever endpoint it is.
-   A call refused for bad input, a missing or wrong key, or a limit isn’t counted.
-   Reference data (`/v1/tax-years`, `/v1/rates`, `/v1/tax-codes/{code}`) needs no key and is never counted.
-   Every call made with a key, counted or not, is in your dashboard’s call log with its `X-Request-Id`, except those refused for going over the calls a second.

## At the limit

-   On Free, once the month’s 100 are used, calls get `402 QUOTA_EXCEEDED` until the 1st. The error’s `upgrade_url` is where to choose a plan with more.
-   Paid plans keep working past their included calculations; the extra are charged as [pricing](https://checktakehomepay.co.uk/pricing) says.
-   More calls a second with one key than the plan allows get `429 RATE_LIMITED`, with `Retry-After` in seconds.
-   We email you when the month reaches 80% and 100% of what your plan includes.

402 Payment Required

```
{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Your free plan's 100 calculations for this month are used. They start again on 1 November 2026, or choose a plan with more.",
    "upgrade_url": "https://checktakehomepay.co.uk/app/billing"
  }
}
```

## Headers

| Header | What it says |
| --- | --- |
| `X-Quota-Limit` | The calculations your plan includes this month. |
| `X-Quota-Remaining` | How many of them are left, after this call. |
| `X-RateLimit-Limit` | Calls a second allowed with this key. |
| `X-RateLimit-Remaining` | How many more this second. |
| `Retry-After` | With a 429: seconds to wait. |
| `X-Request-Id` | This call’s id, as your call log shows it. Quote it when you ask us about a call. |