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

# Rate Limits

> How monthly call quotas work.

The NGN Market API uses a monthly call quota rather than a per-second rate limit. Each plan comes with a fixed number of calls per calendar month. Every response includes a `meta` object showing how many calls you have used, how many remain, and when your quota resets.

## Monthly call quotas

| Plan       | Monthly calls |
| :--------- | ------------: |
| Free       |         3,000 |
| Hobby      |        10,000 |
| Starter    |       100,000 |
| Growth     |       500,000 |
| Business   |     2,000,000 |
| Enterprise |     Unlimited |

Quotas reset on your **billing renewal date** — the same day of the month you first subscribed. Unused calls do not roll over.

## Per-minute burst limits

In addition to monthly quotas, each plan enforces a per-minute request cap to prevent burst abuse. Exceeding this limit returns HTTP `429` with the `RATE_LIMITED` error code. Unlike quota exhaustion, per-minute limits reset automatically after 60 seconds — no action needed.

| Plan       | Requests per minute |
| :--------- | ------------------: |
| Free       |                  30 |
| Hobby      |                  60 |
| Starter    |                 120 |
| Growth     |                 200 |
| Business   |                 300 |
| Enterprise |           Unlimited |

### Rate limit headers

Every response (not just `429`s) includes standard [IETF draft-7](https://www.ietf.org/archive/id/draft-ietf-httpapi-ratelimit-headers-07.html) rate limit headers, so you can track your per-minute budget without parsing the response body:

| Header                | Description                            |
| :-------------------- | :------------------------------------- |
| `RateLimit-Policy`    | The limit and window, e.g. `120;w=60`  |
| `RateLimit-Limit`     | Requests allowed in the current window |
| `RateLimit-Remaining` | Requests left in the current window    |
| `RateLimit-Reset`     | Seconds until the window resets        |

When a request is rejected with `429 RATE_LIMITED`, the response also includes a `Retry-After` header (seconds to wait before retrying) alongside the `meta.retry_after` field in the body.

<Note>
  All API keys on your account share one quota pool. Every call made by any of your keys counts toward the same monthly total.
</Note>

## Tracking usage

Every API response includes a `meta` object. You do not need a separate request to check your usage. For richer analytics like daily call volume, top endpoints, and status code breakdown, use the dedicated [GET /account/usage](/api-reference/account/usage) endpoint.

```json theme={null}
{
  "success": true,
  "data": { },
  "meta": {
    "plan": "starter",
    "calls_used": 4821,
    "calls_remaining": 95179,
    "reset_at": "2026-06-15T23:57:00.000Z"
  }
}
```

| Field             | Type    | Description                                                                          |
| :---------------- | :------ | :----------------------------------------------------------------------------------- |
| `plan`            | string  | Your current plan: `free`, `hobby`, `starter`, `growth`, `business`, or `enterprise` |
| `calls_used`      | integer | Total calls made this month across all your keys                                     |
| `calls_remaining` | integer | Calls left before your quota is exhausted                                            |
| `reset_at`        | string  | ISO 8601 UTC timestamp of your next quota reset                                      |

<Tip>
  Read `meta.calls_remaining` in your application and alert yourself before you hit zero so you are not caught off guard.
</Tip>

## When you exceed your quota

When `calls_used` reaches your monthly limit, all further requests return HTTP `429` with the `QUOTA_EXCEEDED` error code. This is distinct from `RATE_LIMITED`, which is returned when you exceed the per-minute burst cap:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Monthly call limit of 100,000 reached. Resets on 2026-05-01T00:00:00.000Z."
  },
  "meta": {
    "plan": "starter",
    "calls_used": 100000,
    "calls_remaining": 0,
    "reset_at": "2026-06-15T23:57:00.000Z"
  }
}
```

<Warning>
  Once you receive `QUOTA_EXCEEDED`, every request will be rejected until your quota resets or you upgrade.
</Warning>

## What to do when you hit your limit

1. **Wait for the reset.** Check `meta.reset_at` to see the exact UTC time your quota resets on your next billing date.

2. **Upgrade your plan.** Log in to your [developer dashboard](https://ngnmarket.com/developer) and select a higher plan. Upgrades take effect immediately. See [Plans](/plans) for pricing and call limits.

## Reducing unnecessary usage

<AccordionGroup>
  <Accordion title="Cache responses where possible">
    Some endpoints return data that changes infrequently, like the company list (`/companies`) or available dates (`/market/available-dates`). Cache these in your application and refresh on a schedule rather than fetching on every request.
  </Accordion>

  <Accordion title="Avoid polling in tight loops">
    NGX market data is published once per trading day. Polling every few seconds burns through your quota with no benefit. Use a reasonable interval based on how often the data actually changes.
  </Accordion>

  <Accordion title="Use one key per integration">
    Multiple keys do not give you more calls since all keys share one quota pool. Keep your key count to what you actually need.
  </Accordion>
</AccordionGroup>