> ## 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 Google News API

Rate limits and quotas are enforced per plan. Your plan determines how many requests you can make in a period, which API versions you can access, and how far back you can query historical data.

## 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}
{
  "metadata": {
    "id": "c1a2b3d4-e5f6-4789-8abc-def012345678",
    "took_ms": 8,
    "timestamp": "2026-07-30T09:00:00Z"
  },
  "errors": [
    {
      "code": "PAYMENT_REQUIRED",
      "message": "Billing quota exceeded. Please upgrade your plan."
    }
  ]
}
```

## Rate limited

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

```json theme={null}
{
  "metadata": {
    "id": "c1a2b3d4-e5f6-4789-8abc-def012345678",
    "took_ms": 8,
    "timestamp": "2026-07-30T09:00:00Z"
  },
  "errors": [
    {
      "code": "RATE_LIMIT_EXCEEDED",
      "message": "Too many requests. Please try again later."
    }
  ]
}
```

## Plan-dependent limits

Several behaviors depend on your plan's entitlements:

* **Articles per page**: the maximum number of articles returned per page.
* **Retention window**: how far back published articles are available.
* **Historical trends**: how far back topic and date-range queries can go.
* **Custom topics**: access to custom topic identifiers.
* **API version**: the maximum API version your plan can access. Requesting a newer version returns `403`.

## Best practices

* Add retry logic with **exponential backoff** for `429` responses.
* Cache responses where freshness allows.
* Use the `retrieve` endpoint to re-fetch past results by ID instead of re-running expensive searches.
* Contact support if you need a plan change.