# OpenAPI बिलिंग और त्रुटियाँ

platform balance, request और result शुल्क, page billing और सुरक्षित retries को समझें।

यह पृष्ठ `/api/v1/data/*` पर लागू होता है, यानी Felo OpenAPI platform-exclusive APIs पर। Calls **platform balance** का उपयोग करती हैं, जो USD-आधारित service-credit balance है। ये Felo Pro credits consume नहीं करतीं। `/v2` के अंतर्गत पुरानी [Felo APIs](https://openapi.felo.ai/hi/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 की cost समान है, या किसी 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` | कोई नया शुल्क नहीं |

Free status query का मतलब यह नहीं कि underlying generation या export भी free है। 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 actual output के अनुसार settle होती है और unused funds release करती है। Generation और export अलग charges हैं। Repeat-export behavior के लिए [PPT workflow](https://openapi.felo.ai/hi/docs/data-api/guides/felo-ppt.md) देखें।

यदि execution या settlement अनिश्चित हो, तो service उसे reconcile करते समय reservation pending रह सकती है। हर timeout या 5xx को इस बात का प्रमाण न मानें कि कोई work नहीं हुआ या repeated request free है।

अपना available balance और usage [Console Billing](https://openapi.felo.ai/console/billing) में देखें। Account-level top-up guidance के लिए [Billing and Credits](https://openapi.felo.ai/hi/docs/faq/billing-and-credits.md) देखें।

## API के माध्यम से वॉलेट उपयोग पूछताछ करें

Account owners **Felo login token** का उपयोग करके wallet call records inspect कर सकते हैं। यह 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 केवल 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 responses operation के अनुसार भिन्न होती हैं; सभी को एक ही error या `data` envelope में force न करें।

## तय करें कि आगे क्या करना है

| HTTP स्थिति | सामान्य कारण | अगला कदम |
| --- | --- | --- |
| 400 | गुम या अमान्य पैरामीटर | पुनःप्रयास करने से पहले अनुरोध ठीक करें |
| 401 | गुम, अमान्य, निरस्त या समाप्त कुंजी | कुंजी और प्रमाणीकरण हेडर की जाँच करें |
| 402 | अपर्याप्त प्लेटफ़ॉर्म बैलेंस | उपलब्ध बैलेंस और लंबित आरक्षण जाँचें; आवश्यकता होने पर टॉप अप करें |
| 404 | संसाधन अनुपस्थित है या इस खाते के लिए अनुपलब्ध है | ID और बनाने वाले खाते की जाँच करें |
| 409 | संचालन वर्तमान कार्य स्थिति से टकराता है, या निष्पादन अपुष्ट है | त्रुटि कोड पढ़ें और मौजूदा कार्य की जाँच करें; तुरंत उसका डुप्लिकेट न बनाएँ |
| 410 | संसाधन समाप्त या हटाया गया | सहेजी गई फ़ाइल का उपयोग करें; केवल आवश्यकता होने पर नया कार्य बनाएँ |
| 429 | दर सीमा या API कुंजी कोटा पार हो गया | रीसेट जानकारी जाँचें; गति धीमी करें या कोटा रीसेट की प्रतीक्षा करें |
| 502 / 503 / 504 | अपस्ट्रीम, उपलब्धता, समय-सीमा या निपटान विफलता | भुगतान वाले संचालन को पुनःप्रयास करने से पहले जाँचें कि कार्य पहले से मौजूद है या नहीं |

`execution_unconfirmed` (409) और `billing_settlement_pending` (503) को विशेष सावधानी चाहिए: paid work तुरंत दोबारा submit न करें। Known tasks query करें या request ID के साथ support से संपर्क करें। Empty result के साथ successful HTTP status, error response से अलग होती है।

## डुप्लिकेट कार्य बनाए बिना पुनःप्रयास करें

- Read-only task और export-status queries के लिए bounded backoff का उपयोग करें और जहाँ मौजूद हो `Retry-After` का सम्मान करें।
- Saved `task_id` के साथ failed create request के लिए, दूसरी task बनाने से पहले उस task को query करें।
- यदि ID प्राप्त होने से पहले connection विफल हो गया, तो outcome अज्ञात हो सकता है। यह न मानें कि request दोबारा भेजने से deduplicate हो जाएगा।
- 429 के लिए, short rate limit और API key quota window में अंतर करें; बार-बार retry करने से quota reset नहीं हो सकता।
- Configured deadline के बाद retries रोक दें और caller को actionable error दिखाएँ।

Support के लिए endpoint, approximate time, HTTP status और request ID दें। कभी भी पूरी API key शामिल न करें।