> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenomist.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limits, quotas & errors

> How request limits, credit quotas, and error responses work across the Tokenomist API.

Every authenticated response reports your current quota state, and requests are
governed by two independent limits. This page explains both, plus the error
bodies you should handle.

## Response envelope

All endpoints return the same envelope:

```jsonc theme={null}
{
  "metadata": {
    "queryDate": "2026-07-09T10:00:00Z",
    "credit": {
      "used": 213,                       // requests counted this window (near-real-time)
      "limit": 300,                      // your plan's request quota
      "resetAt": "2026-08-01T00:00:00Z"  // when the quota resets (monthly plans)
    }
  },
  "status": true,
  "data": { }
}
```

### `metadata.credit`

| Field            | Type                           | Notes                                                                                                        |
| ---------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| `credit`         | object, optional               | Present on most authenticated responses (success **and** error). Always code defensively — it can be absent. |
| `credit.used`    | integer                        | Requests counted in the current window. Near-real-time — may lag the true count by a request or two.         |
| `credit.limit`   | integer                        | Your plan's request quota for the window.                                                                    |
| `credit.resetAt` | string (RFC3339 UTC), optional | When the quota resets. Present on monthly plans; absent on lifetime-quota plans.                             |

<Info>
  Treat `credit` as optional. It is omitted for unauthenticated requests,
  demo/playground responses, and briefly right after a monthly reset (a stale
  snapshot is dropped rather than shown wrong — it returns on the next request).
</Info>

## Two kinds of limit

Exceeding **either** limit returns `429 Too Many Requests`.

1. **Rate limit** — a short-term cap on how fast you can call the API.
2. **Credit quota** — the number of requests your plan includes per window.

Key rules for the credit quota:

* **Monthly plans reset on the 1st of each month at `00:00:00` UTC.** `credit.resetAt`
  always tells you the exact next reset time. Some plans instead use a lifetime
  quota that does not reset (no `resetAt`).
* **Only successful requests count.** Requests that return an error — `4xx`
  (including auth, validation, and rate-limit errors) and `5xx` — do **not**
  consume credit.
* **The quota is per account**, shared across all API keys on that account.

<Info>
  Exact rate limits and monthly credit allowances depend on your plan. See the
  [pricing page](https://tokenomist.ai/pricing) for the figures that apply to you.
</Info>

## `429 Too Many Requests`

When a quota is exhausted the API returns `429` with a descriptive
`errorMessage`. The status code is always `429`; the message reports how much of
the quota was used and, for monthly plans, when it resets:

```json theme={null}
{
  "status": false,
  "statusCode": 429,
  "errorMessage": "Monthly credit limit reached: 300/300 requests used this month. Quota resets at 2026-08-01T00:00:00Z (00:00 UTC on the 1st of each month)"
}
```

Lifetime-quota plans return the equivalent message without a reset time.

The `429` body also carries the same `metadata.credit` block described above.

<Warning>
  **If your client parses error text:** the `429` `errorMessage` wording changed.
  Match on the `429` **status code**, not on the message string.
</Warning>

### Richer detail with `showError=true`

Appending `?showError=true` (supported across endpoints) adds a human-readable
`errorDetail` with next-step guidance:

```json theme={null}
{
  "status": false,
  "statusCode": 429,
  "errorMessage": "Monthly credit limit reached: 300/300 requests used this month. Quota resets at 2026-08-01T00:00:00Z (00:00 UTC on the 1st of each month)",
  "errorDetail": "Your plan includes 300 API credits per calendar month and you have used 300. The quota resets at 2026-08-01T00:00:00Z (00:00 UTC on the 1st of each month). Wait for the reset or upgrade your plan for a higher monthly limit."
}
```

For lifetime-quota plans, `errorDetail` instead advises contacting support to
raise the limit.