# OpenAPI بلنگ اور غلطیاں

platform balance، request اور result charges، page billing اور محفوظ retries کو سمجھیں۔

یہ صفحہ `/api/v1/data/*` پر لاگو ہوتا ہے، یعنی Felo OpenAPI platform-exclusive APIs۔ Calls **platform balance** استعمال کرتی ہیں، جو USD میں نامزد service-credit balance ہے۔ یہ Felo Pro credits استعمال نہیں کرتیں۔ `/v2` کے تحت پرانی [Felo APIs](https://openapi.felo.ai/ur/docs/api-reference/felo-apis.md) Pro credits استعمال کرتی ہیں۔

## موجودہ قیمتیں پڑھیں

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

یہ public endpoint کسی key کی ضرورت نہیں رکھتا۔ اس کی entries کو operation ID کے مطابق match کریں اور current rate اور billing unit پڑھیں؛ یہ فرض نہ کریں کہ ہر operation کی قیمت ایک جیسی ہے یا کسی example میں دی گئی rate کو اپنی application میں مستقل کر دیں۔

| عمل ID | بلنگ اکائی |
| --- | --- |
| `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` | کوئی نئی چارج نہیں |

ایک مفت status query بنیادی generation یا export کو مفت نہیں بناتی۔ X کے لیے، pagination اور nested returned records billable usage بڑھا سکتے ہیں۔

## توازن اور ریزرویشنز

execution سے پہلے، service operation کے لیے کافی balance reserve کر سکتی ہے۔ successful work اسی reservation کے خلاف settle ہوتا ہے؛ confirmed failure اسے release کر دیتی ہے۔ async tasks میں، ID واپس آنا اس بات کا مطلب نہیں کہ billing پہلے ہی final ہو گئی ہے۔

PPT page pricing creation کے وقت دس pages reserve کرتی ہے۔ successful generation اصل output کے مطابق settlement کرتی ہے اور unused funds release کر دیتی ہے۔ generation اور export الگ charges ہیں۔ repeat-export behavior کے لیے [PPT workflow](https://openapi.felo.ai/ur/docs/data-api/guides/felo-ppt.md) دیکھیں۔

اگر execution یا settlement غیر یقینی ہو، تو service کے reconciliation کرنے تک ایک reservation pending رہ سکتی ہے۔ ہر timeout یا 5xx کو اس بات کا ثبوت نہ سمجھیں کہ کوئی کام نہیں ہوا یا repeated request مفت ہے۔

[Console Billing](https://openapi.felo.ai/console/billing) میں اپنا available balance اور usage دیکھیں۔ account-level top-up guidance کے لیے، [Billing and Credits](https://openapi.felo.ai/ur/docs/faq/billing-and-credits.md) دیکھیں۔

## API کے ذریعے والٹ کے استعمال کی جانچ کریں

Account owners ایک **Felo login token** استعمال کر کے wallet call records دیکھ سکتے ہیں۔ یہ credential Data API calls کے لیے استعمال ہونے والی API Key سے مختلف ہے؛ `FELO_API_KEY` کو اس کی جگہ استعمال نہ کریں۔

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

Records، `data.items` کے تحت ہوتے ہیں؛ `call_type=data` capability calls کو filter کرتا ہے۔ usage کا موازنہ account کی current prices کے ساتھ کریں۔ records پڑھنے سے کوئی اور generation task submit نہیں ہوتا۔ account review اور top-ups کے لیے Console Billing بدستور دستیاب ہے۔

## غلطیوں کو احتیاط سے پڑھیں

پہلے HTTP status چیک کریں۔ errors ان دو shapes میں سے کسی ایک کو استعمال کر سکتی ہیں؛ نیچے دی گئی values صرف وضاحتی ہیں:

```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` واپس آئے تو اسے محفوظ رکھیں۔ successful responses operation کے مطابق مختلف ہوتی ہیں؛ انہیں زبردستی ایک ہی error یا `data` envelope میں نہ ڈالیں۔

## اگلا کیا کرنا ہے طے کریں

| HTTP حالت | عام سبب | اگلا قدم |
| --- | --- | --- |
| 400 | پیرامیٹر غائب یا غلط | دوبارہ کوشش سے پہلے درخواست درست کریں |
| 401 | کلید غائب، غلط، منسوخ یا ختم شدہ | کلید اور تصدیقی ہیڈر چیک کریں |
| 402 | پلیٹ فارم توازن ناکافی | دستیاب توازن اور زیرِ التوا ریزرویشنز چیک کریں؛ اگر ضرورت ہو تو رقم شامل کریں |
| 404 | وسیلہ غائب ہے یا اس کھاتے کے لیے ناقابلِ رسائی ہے | ID اور بنانے والے کھاتے کو چیک کریں |
| 409 | کارروائی موجودہ کام کی حالت سے متصادم ہے، یا عمل کی تصدیق نہیں ہوئی | غلطی کوڈ پڑھیں اور موجودہ کام سے پوچھ گچھ کریں؛ فوری طور پر اس کی نقل نہ بنائیں |
| 410 | وسیلہ ختم ہو چکا یا حذف ہو چکا | محفوظ فائل استعمال کریں؛ صرف ضرورت ہو تو نیا کام بنائیں |
| 429 | رفتار حد یا API کلید کوٹہ سے تجاوز | دوبارہ سیٹ کی معلومات دیکھیں؛ رفتار کم کریں یا کوٹہ ری سیٹ ہونے کا انتظار کریں |
| 502 / 503 / 504 | upstream، دستیابی، وقفۂ انتظار یا تصفیہ کی ناکامی | ادائیگی والے عمل کو دوبارہ آزمانے سے پہلے دیکھیں آیا کام پہلے سے موجود ہے |

`execution_unconfirmed` (409) اور `billing_settlement_pending` (503) خاص احتیاط چاہتے ہیں: paid work فوراً دوبارہ submit نہ کریں۔ معلوم tasks query کریں یا request ID کے ساتھ support سے رابطہ کریں۔ ایک empty result کے ساتھ successful HTTP status، error response سے مختلف ہوتا ہے۔

## بغیر نقل کام بنائے دوبارہ کوشش کریں

- read-only task اور export-status queries کے لیے bounded backoff استعمال کریں اور جہاں موجود ہو `Retry-After` کا احترام کریں۔
- اگر create request ناکام ہو اور `task_id` محفوظ ہو، تو ایک اور task بنانے سے پہلے اسی task کو query کریں۔
- اگر ID موصول ہونے سے پہلے connection ناکام ہو گیا، تو outcome نامعلوم ہو سکتا ہے۔ یہ فرض نہ کریں کہ دوبارہ بھیجنے سے request deduplicate ہو جائے گی۔
- 429 کے لیے، مختصر rate limit اور API key quota window میں فرق کریں؛ بار بار retry کرنے سے quota reset نہیں ہو سکتی۔
- configured deadline کے بعد retries روک دیں اور caller کو ایک قابلِ عمل error دکھائیں۔

support کے لیے، endpoint، تخمینی وقت، HTTP status اور request ID فراہم کریں۔ مکمل API key کبھی شامل نہ کریں۔