> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-parschat.parstechai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-parschat.parstechai.com/_mcp/server.

# خطاها

> همه وضعیت‌ها و کدهایی که برمی‌گردانیم، و اینکه هر کدام یعنی چه کاری باید بکنید.

> **Warning**
>
> **نسخه پیش‌انتشار `v1`، منتشرشده در 2026-09-14.** این صفحه به شکل API متعهد است،
> نه به تاریخ مشخصی. دقیقاً همان چیزی را می‌سازیم که اینجا مستند شده است. شکل API تا
> **2026-10-14** هنوز ممکن است تغییر کند؛ پس از آن، تغییرات از [نسخه‌بندی و پایداری](/documentation/reference/versioning-stability) پیروی می‌کنند.
>
> این بنر با راه‌اندازی هر مسیر، صفحه به صفحه برداشته می‌شود. تا وقتی اینجاست، بر اساس قرارداد
> پیاده‌سازی کنید و فرض کنید آن مسیر هنوز قابل فراخوانی نیست.

## شکل خطا \[#shape]

```json
{
  "error": {
    "code": "plan_inactive",
    "message": "Your plan is not active.",
    "request_id": "req_8f2Kq9mR"
  }
}
```

**همیشه `request_id` را لاگ کنید.** وقتی با پشتیبانی تماس می‌گیرید، همین مقدار است که به ما امکان می‌دهد درخواست دقیق شما را پیدا کنیم.

## کدها \[#codes]

| وضعیت | `code`                      | معنا                                                            | چه کار کنید                                                                                                                               |
| ----- | --------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | `bad_request`               | پارامتری جا افتاده، قابل تجزیه نیست، یا خارج از بازه است        | رشته کوئری را اصلاح کنید                                                                                                                  |
| `401` | `invalid_key`               | کلید وجود ندارد، اشتباه است، باطل شده یا منقضی شده است          | هدر را بررسی کنید؛ از فروش کلید جدید بخواهید                                                                                              |
| `403` | `plan_inactive`             | بسته منقضی شده است                                              | گذرا نیست. [وقتی بسته منقضی می‌شود](/documentation/guides/when-a-plan-lapses) را ببینید                                                   |
| `403` | `capacity_exhausted`        | ظرفیت ربات یا کانال تمام شده است                                | یکی را حذف کنید، یا از فروش بخواهید ظرفیت را بالا ببرد                                                                                    |
| `403` | `channel_not_in_plan`       | بسته شما این نوع کانال را شامل نمی‌شود                          | با فروش تماس بگیرید                                                                                                                       |
| `403` | `attachment_not_in_plan`    | بسته شما این نوع فایل را شامل نمی‌شود                           | با فروش تماس بگیرید                                                                                                                       |
| `403` | `forbidden`                 | نقش لازم روی حساب شما نیست                                      | با مدیر حساب خود تماس بگیرید                                                                                                              |
| `404` | `not_found`                 | چنین منبعی وجود ندارد، **یا متعلق به شما نیست**                 | شناسه را بررسی کنید                                                                                                                       |
| `409` | `conflict`                  | `external_id` تکراری، یا این نوع کانال از قبل وجود دارد         | از مقدار دیگری استفاده کنید                                                                                                               |
| `409` | `handshake_pending`         | یک handshake اینستاگرام منقضی‌نشده وجود دارد                    | صبر کنید تا منقضی شود، یا از همان استفاده کنید                                                                                            |
| `410` | `handshake_expired`         | مالک صفحه بیش از حد طول داد                                     | یک handshake جدید شروع کنید                                                                                                               |
| `422` | `validation_failed`         | درخواست نادرست است                                              | بدنه را اصلاح کنید                                                                                                                        |
| `422` | `return_url_not_configured` | هیچ آدرس بازگشتی برای شما تنظیم نشده است                        | پیش از اتصال با ما تماس بگیرید                                                                                                            |
| `429` | `rate_limited`              | درخواست‌ها بیش از حد است                                        | مکث کنید و سپس دوباره تلاش کنید. `details` محدودیت شما را مشخص می‌کند. [محدودیت نرخ درخواست](/documentation/guides/rate-limits) را ببینید |
| `500` | `internal_error`            | مشکلی سمت ما رخ داده است                                        | با فاصله‌گذاری فزاینده (backoff) دوباره تلاش کنید؛ اگر ادامه داشت، `request_id` را به ما بدهید                                            |
| `503` | `upstream_unavailable`      | یک ارائه‌دهنده کانال، یا سرویس هوش مصنوعی ما، از دسترس خارج است | با backoff دوباره تلاش کنید                                                                                                               |

## `400` و `422` دو خطای متفاوت‌اند \[#400-and-422-are-different-failures]

`400` یعنی درخواست اصلاً به مرحله اعتبارسنجی نرسیده است: یک پارامتر الزامی وجود ندارد، یک
timestamp قابل تجزیه نیست، یا `limit` خارج از بازه است. `422` یعنی درخواست ساختار درستی داشته اما
محتوای آن رد شده است، مثلاً قانون کامنتی که نه پاسخ دارد و نه دایرکت.

```json
{
  "error": {
    "code": "bad_request",
    "message": "`from` must be earlier than `to`.",
    "request_id": "req_8f2Kq9mR",
    "details": { "from": "2026-09-30T00:00:00Z", "to": "2026-09-01T00:00:00Z" }
  }
}
```

## یک کد برای همه کلیدهای نامعتبر \[#one-code-for-every-bad-key]

کلید جاافتاده، اشتباه، باطل‌شده یا منقضی، همه با `401 invalid_key` پاسخ داده می‌شوند. اگر کلید
منقضی را از کلید ناشناخته جدا کنیم، به هر کسی که کلید لورفته‌ای در دست دارد تأیید کرده‌ایم که آن
کلید زمانی واقعی بوده است. تاریخ انقضای کلید شما در توافق‌نامه‌ای است که فروش برایتان فرستاده؛ پیش
از آن تاریخ کلید جدید درخواست کنید.

## `404`، نه `403`، برای منابع دیگران \[#404-not-403-for-someone-elses-resources]

اگر منبعی را درخواست کنید که وجود دارد اما متعلق به شریک دیگری است، **`404` دریافت می‌کنید، نه
`403`**. پاسخ `403` وجود آن شناسه را تأیید می‌کرد، و این اطلاعاتی است که نباید بتوانید آن را
کاوش کنید.

## `details`

برخی خطاها، جایی که یک عدد به شما در اقدام کمک می‌کند، یک شیء `details` همراه دارند:

```json
{
  "error": {
    "code": "capacity_exhausted",
    "message": "You have reached the maximum number of channels your plan allows.",
    "request_id": "req_8f2Kq9mR",
    "details": { "occupied": 10, "requested": 1, "capacity": 10 }
  }
}
```

این شیء **هرگز** در `401` یا `404` نمی‌آید؛ آنجا جزئیات بیشتر چیزی را تأیید می‌کرد که نباید
بفهمید.

## کدام خطاها ارزش تلاش دوباره دارند \[#which-errors-are-worth-retrying]

| تلاش دوباره کنید          | تلاش دوباره نکنید                             |
| ------------------------- | --------------------------------------------- |
| `429` (پس از مکث)         | `400`. درخواست نادرست است                     |
|                           | `401`. کلید خودبه‌خود درست نمی‌شود            |
| `500`، `503` (با backoff) | `403`. وضعیت بسته یا نقش است، نه یک خطای گذرا |
|                           | `422`. بدنه اشتباه است                        |
|                           | `409`. تعارض واقعی است                        |

> **Info**
>
> ما هرگز نام میزبان یا سرویس داخلی را در خطا نمی‌آوریم. اگر لازم است بدانید *چرا* چیزی در لایه‌های
> بالادستی شکست خورده، `request_id` خود را برای مدیر حساب‌تان بفرستید.