# صورتحساب و خطاهای OpenAPI

موجودی پلتفرم، هزینه‌های درخواست و نتیجه، صورتحساب صفحه و تلاش‌های مجدد ایمن را درک کنید.

این صفحه برای `/api/v1/data/*`، یعنی APIهای اختصاصی پلتفرم Felo OpenAPI، اعمال می‌شود. تماس‌ها از **موجودی پلتفرم**، یعنی موجودی اعتبار خدمات به دلار آمریکا، استفاده می‌کنند. این‌ها اعتبارات Felo Pro را مصرف نمی‌کنند. [APIهای قدیمی Felo](https://openapi.felo.ai/fa/docs/api-reference/felo-apis.md) تحت `/v2` از اعتبارات Pro استفاده می‌کنند.

## قیمت‌های فعلی را بخوانید

```bash
curl -sS https://openapi.felo.ai/api/v1/data/prices
```

این پایانه عمومی به هیچ کلیدی نیاز ندارد. ورودی‌های آن را با شناسه عملیات تطبیق دهید و نرخ و واحد صورتحساب فعلی را بخوانید؛ فرض نکنید هر عملیات هزینه یکسانی دارد یا یک نرخ نمونه را در برنامه خود ثابت کنید.

| شناسه عملیات | واحد صورتحساب |
|---|---|
| `web.search`, `web.read`, `chat` | درخواست |
| `x.user.info`, `x.user.search`, `x.user.tweets`, `x.tweet.search`, `x.tweet.replies` | نتیجه بازگردانده‌شده |
| `ppt.generate` | صفحه تولیدشده |
| `ppt.export` | درخواست خروجی |
| `ppt.generate.status`, `ppt.generate.historical`, `ppt.export.status`, `ppt.delete` | بدون هزینه جدید |

یک پرس‌وجوی وضعیت رایگان، تولید یا خروجی زیرین را رایگان نمی‌کند. برای X، صفحه‌بندی و رکوردهای تودرتوی بازگردانده‌شده ممکن است استفاده قابل‌صورتحساب را افزایش دهند.

## موجودی و رزروها

پیش از اجرا، سرویس می‌تواند موجودی کافی را برای عملیات رزرو کند. کار موفق بر اساس آن رزرو تسویه می‌شود؛ شکست تأییدشده آن را آزاد می‌کند. برای وظایف غیرهمزمان، بازگرداندن یک شناسه به این معنا نیست که صورتحساب از پیش نهایی شده است.

قیمت‌گذاری صفحه PPT در ایجاد، هزینه ده صفحه را رزرو می‌کند. تولید موفق خروجی واقعی را تسویه می‌کند و وجوه استفاده‌نشده را آزاد می‌سازد. تولید و خروجی دو هزینه جداگانه هستند. برای رفتار خروجیِ تکراری، به [گردش‌کار PPT](https://openapi.felo.ai/fa/docs/data-api/guides/felo-ppt.md) مراجعه کنید.

اگر اجرا یا تسویه نامطمئن باشد، ممکن است یک رزرو در حالت معلق باقی بماند در حالی که سرویس آن را تطبیق می‌دهد. هر زمان‌اِتمام یا 5xx را به‌عنوان اثبات اینکه هیچ کاری انجام نشده یا درخواست تکراری رایگان است، تلقی نکنید.

موجودی در دسترس و استفاده خود را در [Console Billing](https://openapi.felo.ai/console/billing) بررسی کنید. برای راهنمای شارژ در سطح حساب، به [صورتحساب و اعتبارات](https://openapi.felo.ai/fa/docs/faq/billing-and-credits.md) مراجعه کنید.

## استفاده از کیف پول را از طریق API پرس‌وجو کنید

مالکین حساب می‌توانند با استفاده از یک **توکن ورود Felo** سوابق تماس کیف پول را بررسی کنند. این اعتبار با API Key استفاده‌شده برای تماس‌های Data API متفاوت است؛ `FELO_API_KEY` را جایگزین نکنید.

```bash
curl -sS 'https://openapi.felo.ai/api/wallet/usage?call_type=data' \
  -H 'Authorization: Bearer YOUR_FELO_LOGIN_TOKEN'
```

سوابق در `data.items` هستند؛ `call_type=data` تماس‌های قابلیت را فیلتر می‌کند. استفاده را با قیمت‌های فعلی حساب مقایسه کنید. خواندن سوابق یک وظیفه تولید دیگر ارسال نمی‌کند. Console Billing برای بررسی و شارژ حساب همچنان در دسترس است.

## خطاها را با احتیاط بخوانید

ابتدا وضعیت HTTP را بررسی کنید. خطاها می‌توانند یکی از این دو شکل را داشته باشند؛ مقادیر زیر نمایشی هستند:

```json
{"error":{"code":"invalid_parameter","message":"Check the request fields"},"request_id":"example-request-id"}
```

```json
{"status":402,"code":"INSUFFICIENT_BALANCE","message":"Insufficient balance","request_id":"example-request-id"}
```

در صورت وجود، `error.code` / `error.message` را بخوانید، وگرنه `code` / `message` را. `request_id` را در صورت بازگشت حفظ کنید. پاسخ‌های موفق بسته به عملیات متفاوت‌اند؛ آن‌ها را همگی در یک پوشش خطا یا `data` قرار ندهید.

## تصمیم بگیرید قدم بعدی چیست

| وضعیت HTTP | علت رایج | قدم بعدی |
|---|---|---|
| 400 | پارامتر مفقود یا نامعتبر | پیش از تلاش مجدد درخواست را اصلاح کنید |
| 401 | کلید مفقود، نامعتبر، باطل‌شده یا منقضی‌شده | کلید و هدر احراز هویت را بررسی کنید |
| 402 | موجودی پلتفرم ناکافی | موجودی در دسترس و رزروهای در حال انتظار را بررسی کنید؛ در صورت نیاز شارژ کنید |
| 404 | منبع برای این حساب مفقود یا غیرقابل‌دسترسی | شناسه و حساب ایجادکننده را بررسی کنید |
| 409 | عملیات با وضعیت فعلی وظیفه تداخل دارد، یا اجرا تأیید نشده است | کد خطا را بخوانید و وظیفه موجود را پرس‌وجو کنید؛ بلافاصله آن را تکرار نکنید |
| 410 | منبع منقضی یا حذف شده است | از فایل ذخیره‌شده استفاده کنید؛ فقط در صورت نیاز یک وظیفه جدید ایجاد کنید |
| 429 | محدودیت نرخ یا سهمیه API Key رد شده است | اطلاعات بازنشانی را بررسی کنید؛ سرعت را کم کنید یا منتظر بازنشانی سهمیه بمانید |
| 502 / 503 / 504 | خطای بالادستی، دسترس‌پذیری، زمان‌اِتمام یا تسویه | پیش از تلاش مجدد برای یک عملیات پولی، بررسی کنید که آیا کار از قبل وجود دارد یا نه |

`execution_unconfirmed` (409) و `billing_settlement_pending` (503) نیاز به دقت ویژه دارند: کار پولی را فوراً دوباره ارسال نکنید. وظایف شناخته‌شده را پرس‌وجو کنید یا با request_id با پشتیبانی تماس بگیرید. وضعیت HTTP موفق همراه با نتیجه خالی با یک پاسخ خطا متفاوت است.

## بدون ایجاد کار تکراری تلاش مجدد کنید

- برای پرس‌وجوهای فقط‌خواندنیِ وضعیت وظیفه و وضعیت خروجی، از عقب‌گرد محدود استفاده کنید و در صورت وجود `Retry-After` آن را رعایت کنید.
- برای یک درخواست ایجاد ناموفق با `task_id` ذخیره‌شده، پیش از ایجاد یکی دیگر، همان وظیفه را پرس‌وجو کنید.
- اگر اتصال پیش از دریافت شناسه شکست خورد، نتیجه ممکن است نامعلوم باشد. فرض نکنید ارسال دوباره درخواست را از تکرار محافظت می‌کند.
- برای 429، بین یک محدودیت نرخ کوتاه و یک پنجره سهمیه API Key تفاوت قائل شوید؛ تلاش مجدد مکرر نمی‌تواند سهمیه را بازنشانی کند.
- تلاش‌های مجدد را پس از مهلت پیکربندی‌شده متوقف کنید و یک خطای قابل‌اقدام به فراخواننده نشان دهید.

برای پشتیبانی، پایان‌نقطه، زمان تقریبی، وضعیت HTTP و request_id را ارائه کنید. هرگز کل API Key را شامل نکنید.