# محدودیت‌ها و پلن‌ها

> سقف درخواست در دقیقه، سهمیهٔ روزانه، حداکثر ردیف در هر پاسخ و خانواده‌های دادهٔ هر پلن روشا، و اینکه در رسیدن به سقف چه پاسخی می‌گیرید.
> Source: https://poolick.ir/docs/limits/

هر پلن سه چیز را مشخص می‌کند: چند درخواست در دقیقه، چند درخواست در روز، و دسترسی به کدام خانواده‌های داده. سقف ردیف در هر پاسخ برای همهٔ پلن‌ها یکی است: ۵٬۰۰۰ ردیف در REST و ۵۰۰ ردیف در MCP.

## پلن‌ها چه سقف‌هایی دارند؟

جدول زیر پلن‌ها را مطابق وضعیت آبان ۱۴۰۵ نشان می‌دهد. پلن‌ها ممکن است تغییر کنند؛ مرجع به‌روز صفحهٔ [قیمت‌ها](/pricing/) و نسخهٔ ماشین‌خوان آن [`/pricing.json`](/pricing.json) است.

| پلن | درخواست در دقیقه | درخواست در روز | `history` | `intraday` | `mcp` | تعداد کلید |
|---|---|---|---|---|---|---|
| رایگان (`free`) | 30 | 1,000 | دارد | ندارد | دارد | 1 |
| پایه (`starter`) | 60 | 10,000 | دارد | ندارد | دارد | 2 |
| حرفه‌ای (`pro`) | 120 | 20,000 | دارد | دارد | دارد | 3 |
| سازمانی (`business`) | توافقی | توافقی | دارد | دارد | دارد | توافقی |
| دانشگاهی (`academic`) | 60 | 10,000 | دارد | ندارد | دارد | 2 |

پلن دانشگاهی برای دانشجویان و پژوهشگران رایگان است و از [پنل](/panel/) درخواست می‌شود.

## سقف دقیقه‌ای (rate limit) چطور حساب می‌شود؟

سقف دقیقه‌ای برای هر کلید و در دقیقه‌های ثابت تقویمی شمرده می‌شود: شمارنده در ثانیهٔ `:00` هر دقیقه صفر می‌شود. پنجرهٔ لغزان در کار نیست.

- با پلن رایگان می‌توانید ۳۰ درخواست را در هر لحظه از یک دقیقه بفرستید. درخواست سی‌ویکم در همان دقیقه `429 rate_limited` می‌گیرد.
- سرآیند `Retry-After` می‌گوید چند ثانیه تا شروع دقیقهٔ بعد مانده است (عددی بین ۱ تا ۶۰).

## سهمیهٔ روزانه چه زمانی صفر می‌شود؟

سهمیهٔ روزانه برای هر کلید شمرده می‌شود و نیمه‌شب به وقت تهران صفر می‌شود. پس از پر شدن آن، هر درخواست `429 quota_exceeded` با `Retry-After: 3600` می‌گیرد.

:::caution
درخواستی که به‌خاطر سقف دقیقه‌ای `429` می‌گیرد هم از سهمیهٔ روزانه کم می‌شود. حلقهٔ تلاش مجدد بدون مکث سهمیهٔ روز را مصرف می‌کند؛ همیشه به اندازهٔ `Retry-After` صبر کنید.
:::

## چه درخواست‌هایی شمرده می‌شوند؟

هر درخواست به `/v1/…` و هر درخواست HTTP به `/mcp` یک واحد از هر دو سقف کم می‌کند، از جمله این‌ها:

- endpointهای همیشه مجاز مثل جست‌وجوی نماد و تقویم؛
- درخواست‌هایی که `404` یا `422` می‌گیرند؛
- مسیرهای ناشناخته زیر `/v1/`.

درخواست‌های ردشده با `401` و `403` از سقف‌ها کم نمی‌کنند، ولی مثل بقیه در آمار مصرف پنل ثبت می‌شوند. یک گفت‌وگوی دستیار هوش مصنوعی از راه MCP معمولاً چند درخواست HTTP می‌فرستد؛ [MCP](/docs/mcp/) را ببینید.

## در هر پاسخ چند ردیف می‌گیرم؟

`limit` در endpointهای سابقه حداکثر ۵٬۰۰۰ در REST و ۵۰۰ در MCP است.

| endpoint | پیش‌فرض `limit` | سقف |
|---|---|---|
| `/v1/instruments/{ref}/daily`، `/client-type`، `/v1/indices/{ref}/daily`، `/v1/funds/{ref}/history`، `/v1/funds/{ref}/snapshots` | 1000 | 5000 |
| `/v1/instruments` (جست‌وجو) | 20 | 100 |
| `/v1/funds` (فهرست) | 50 | 500 |
| `/v1/instruments/{ref}/trades` | بدون `limit` | 20,000 ردیف در هر روز |
| ابزارهای MCP | بسته به ابزار | 500 |

در REST، `limit` بیشتر از سقف خطای `422` می‌گیرد. برای بازه‌های بلندتر، با تاریخ صفحه‌بندی کنید: [قراردادها و قالب‌ها](/docs/conventions/).

## هر خانوادهٔ داده کدام مسیرها را دارد؟

هر مسیر در یکی از چهار خانواده است و پلن باید آن خانواده را داشته باشد؛ وگرنه پاسخ `403 plan_forbids` است.

| خانواده | مسیرها |
|---|---|
| همیشه مجاز | `/v1/instruments`، `/v1/instruments/{ref}`، `/v1/calendar`، `/v1/funds`، `/v1/funds/types`، `/v1/funds/{ref}` |
| `history` | `/v1/instruments/{ref}/daily`، `/v1/instruments/{ref}/adjustments`، `/v1/instruments/{ref}/client-type`، `/v1/indices/{ref}/daily`، `/v1/funds/{ref}/history`، `/v1/funds/{ref}/snapshots` |
| `intraday` | `/v1/instruments/{ref}/quote`، `/v1/instruments/{ref}/trades`، `/v1/instruments/{ref}/bars` |
| `mcp` | هر چیزی زیر `/mcp` |

«همیشه مجاز» یعنی هر پلنی به آن دسترسی دارد؛ این مسیرها هم کلید معتبر می‌خواهند و در سقف‌ها شمرده می‌شوند.

## وقتی به سقف می‌رسم چه می‌شود؟

پاسخ `429` با بدنهٔ JSON و سرآیند `Retry-After` می‌گیرید. سرویس درخواست را در صف نمی‌گذارد و حساب شما مسدود نمی‌شود.

| وضعیت | `code` | `Retry-After` | چه کنید |
|---|---|---|---|
| 429 | `rate_limited` | ثانیه‌های مانده تا دقیقهٔ بعد | همان‌قدر صبر کنید و دوباره بفرستید |
| 429 | `quota_exceeded` | `3600` | تا نیمه‌شب تهران صبر کنید یا پلن را ارتقا دهید |

```json
{"detail": "Rate limit of 30 requests/minute exceeded.", "code": "rate_limited"}
```

نمونهٔ کد تلاش مجدد در [خطاها](/docs/errors/) است. مصرف هر کلید را در [پنل](/panel/) می‌بینید.