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

# Rate limits

> Rate limits and quota behavior for the Bonai News API

Rate limits and quotas are enforced per plan. Your plan determines how many requests you can make in a period, how large result pages can be, and which topics and languages you can access.

## How limits are enforced

Limits are checked when your request is authenticated. When you exceed a limit, the API returns an error and sets an `X-Auth-Reason` response header with the reason.

## Quota exceeded

When you exceed your plan's request quota, the API returns **`402 Payment Required`**:

```json theme={null}
{
  "success": false,
  "code": 402,
  "message": "Billing quota exceeded. Please upgrade your plan.",
  "fields": []
}
```

## Rate limited

When you exceed your plan's rate limit, the API returns **`429 Too Many Requests`**:

```json theme={null}
{
  "success": false,
  "code": 429,
  "message": "Too many requests. Please try again later.",
  "fields": []
}
```

## Plan-dependent limits

Several behaviors depend on your plan's entitlements:

* **Articles per page**: the maximum number of articles returned per page. Your `limit` parameter is capped at this value.
* **Historical trends**: how far back trending data is available. Requests for older dates return `402`.
* **Allowed topics and languages**: the topics and languages you can query. Unsupported values return `402`.
* **Article content**: full article `content` is only returned for plans that include it.

## Best practices

* Add retry logic with **exponential backoff** for `429` responses.
* Cache responses where freshness allows.
* Keep `limit` within your plan's per-page allowance.
* Contact support if you need a plan change.