# OpenAPI বিলিং এবং ত্রুটি

প্ল্যাটফর্ম ব্যালেন্স, রিকোয়েস্ট ও ফলাফলের চার্জ, পেজ বিলিং এবং নিরাপদ রিট্রাই সম্পর্কে বুঝুন।

এই পৃষ্ঠা `/api/v1/data/*`-এর জন্য প্রযোজ্য, অর্থাৎ Felo OpenAPI platform-exclusive API-গুলো। Call-গুলো **platform balance** ব্যবহার করে, যা USD-এ নির্ধারিত service-credit balance। এগুলো Felo Pro credits ব্যবহার করে না। `/v2`-এর পুরোনো [Felo APIs](https://openapi.felo.ai/bn/docs/api-reference/felo-apis.md) Pro credits ব্যবহার করে।

## বর্তমান মূল্য পড়ুন

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

এই public endpoint-এর জন্য কোনো key দরকার নেই। Operation ID দিয়ে এর entry-গুলো match করুন এবং বর্তমান rate ও billing unit পড়ুন; সব operation-এর খরচ একই—এমন ধরে নেবেন না বা example থেকে rate নিয়ে আপনার application-এ স্থির করে রাখবেন না।

| কার্যক্রম পরিচায়ক | বিলিং একক |
| --- | --- |
| `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` | নতুন কোনো চার্জ নয় |

একটি free status query মানে অন্তর্নিহিত generation বা export বিনামূল্যে—এমন নয়। X-এর ক্ষেত্রে, pagination এবং nested ফেরত আসা record billable usage বাড়াতে পারে।

## ব্যালেন্স এবং সংরক্ষণ

Execution-এর আগে, service operation-এর জন্য যথেষ্ট balance reserve করতে পারে। Successful work সেই reservation-এর বিরুদ্ধে settle হয়; নিশ্চিত failure হলে তা release হয়। Async task-এর ক্ষেত্রে, ID ফেরত আসা মানেই billing ইতিমধ্যে final—এমন নয়।

PPT page pricing creation-এর সময় দশ পেজ reserve করে। Successful generation প্রকৃত output অনুযায়ী settle করে এবং unused fund release করে। Generation এবং export আলাদা charge। Repeat-export behavior-এর জন্য [PPT workflow](https://openapi.felo.ai/bn/docs/data-api/guides/felo-ppt.md) দেখুন।

Execution বা settlement অনিশ্চিত হলে, service reconcile করার সময় একটি 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/bn/docs/faq/billing-and-credits.md) দেখুন।

## API-এর মাধ্যমে ওয়ালেট ব্যবহার অনুধাবন করুন

Account owner-রা **Felo login token** ব্যবহার করে wallet call record পরীক্ষা করতে পারেন। এই credential Data API call-এর জন্য ব্যবহৃত 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'
```

Record-গুলো `data.items`-এর অধীনে থাকে; `call_type=data` capability call filter করে। Account-এর বর্তমান মূল্যের সাথে usage তুলনা করুন। Record পড়া আরেকটি generation task submit করে না। Account review এবং top-up-এর জন্য Console Billing এখনও উপলভ্য।

## ত্রুটিগুলি সুরক্ষিতভাবে পড়ুন

প্রথমে HTTP status পরীক্ষা করুন। Error এই দুইটির যেকোনো shape ব্যবহার করতে পারে; নিচের value-গুলো illustrative:

```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 response operation অনুযায়ী ভিন্ন হয়; সবকিছুকে একই error বা `data` envelope-এ বাধ্য করবেন না।

## পরবর্তী কী করবেন তা নির্ধারণ করুন

| HTTP অবস্থা | সাধারণ কারণ | পরবর্তী পদক্ষেপ |
| --- | --- | --- |
| 400 | অনুপস্থিত বা অবৈধ প্যারামিটার | আবার চেষ্টা করার আগে অনুরোধটি ঠিক করুন |
| 401 | অনুপস্থিত, অবৈধ, প্রত্যাহারকৃত বা মেয়াদোত্তীর্ণ কী | কী এবং প্রমাণীকরণ হেডার পরীক্ষা করুন |
| 402 | অপর্যাপ্ত প্ল্যাটফর্ম ব্যালেন্স | উপলব্ধ ব্যালেন্স এবং মুলতুবি সংরক্ষণ পরীক্ষা করুন; প্রয়োজন হলে রিচার্জ করুন |
| 404 | সম্পদ অনুপস্থিত অথবা এই অ্যাকাউন্টের জন্য অপ্রাপ্য | পরিচায়ক এবং তৈরি করা অ্যাকাউন্ট পরীক্ষা করুন |
| 409 | কার্যটি বর্তমান কাজের অবস্থার সঙ্গে সাংঘর্ষিক, অথবা নির্বাহ অনিশ্চিত | ত্রুটি কোড পড়ুন এবং বিদ্যমান কাজটি অনুসন্ধান করুন; সঙ্গে সঙ্গে এটি নকল করবেন না |
| 410 | সম্পদের মেয়াদ শেষ বা মুছে ফেলা হয়েছে | সংরক্ষিত ফাইল ব্যবহার করুন; প্রয়োজনে নতুন কাজ তৈরি করুন |
| 429 | হারসীমা বা API কী কোটা অতিক্রান্ত | রিসেট তথ্য পরীক্ষা করুন; গতি কমান বা কোটা রিসেট হওয়া পর্যন্ত অপেক্ষা করুন |
| 502 / 503 / 504 | আপস্ট্রিম, প্রাপ্যতা, সময়সীমা বা নিষ্পত্তি ব্যর্থতা | আবার চেষ্টা করার আগে কাজটি ইতিমধ্যে আছে কি না পরীক্ষা করুন |

`execution_unconfirmed` (409) এবং `billing_settlement_pending` (503)-এর ক্ষেত্রে বিশেষ সতর্কতা দরকার: সঙ্গে সঙ্গে paid work পুনরায় submit করবেন না। পরিচিত task query করুন বা request ID সহ support-এ যোগাযোগ করুন। Empty result-সহ successful HTTP status error response-এর থেকে ভিন্ন।

## নতুন নকল কাজ তৈরি না করে আবার চেষ্টা করুন

- Read-only task এবং export-status query-র জন্য bounded backoff ব্যবহার করুন এবং উপস্থিত থাকলে `Retry-After` মানুন।
- Saved `task_id`-সহ failed create request-এর ক্ষেত্রে, আরেকটি তৈরি করার আগে সেই task query করুন।
- ID পাওয়ার আগেই connection ব্যর্থ হলে outcome অজানা থাকতে পারে। Resending request deduplicate করবে—এমন ধরে নেবেন না।
- 429-এর জন্য, একটি short rate limit এবং একটি API key quota window আলাদা করুন; বারবার retry করলে quota reset হবে না।
- Configured deadline-এর পরে retry বন্ধ করুন এবং caller-কে একটি actionable error দেখান।

Support-এর জন্য endpoint, আনুমানিক সময়, HTTP status এবং request ID দিন। কখনও সম্পূর্ণ API key অন্তর্ভুক্ত করবেন না।