# Pengebilan dan Ralat OpenAPI

Fahami baki platform, caj permintaan dan hasil, pengebilan halaman dan percubaan semula yang selamat.

Halaman ini terpakai kepada `/api/v1/data/*`, API eksklusif platform Felo OpenAPI. Panggilan menggunakan **baki platform**, baki kredit perkhidmatan dalam denominasi USD. Ia tidak menggunakan kredit Felo Pro. [API Felo](https://openapi.felo.ai/ms/docs/api-reference/felo-apis.md) yang lebih lama di bawah `/v2` menggunakan kredit Pro.

## Baca harga semasa

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

Titik akhir awam ini tidak memerlukan kunci. Padankan entrinya mengikut ID operasi dan baca kadar semasa serta unit pengebilan; jangan anggap setiap operasi berharga sama atau membekukan kadar daripada contoh ke dalam aplikasi anda.

| ID Operasi | Unit pengebilan |
|---|---|
| `web.search`, `web.read`, `chat` | Permintaan |
| `x.user.info`, `x.user.search`, `x.user.tweets`, `x.tweet.search`, `x.tweet.replies` | Hasil dipulangkan |
| `ppt.generate` | Halaman dijana |
| `ppt.export` | Permintaan eksport |
| `ppt.generate.status`, `ppt.generate.historical`, `ppt.export.status`, `ppt.delete` | Tiada caj baharu |

Pertanyaan status percuma tidak menjadikan penjanaan atau eksport asas percuma. Untuk X, paginasi dan rekod bersarang yang dipulangkan boleh meningkatkan penggunaan yang boleh dibilkan.

## Baki dan tempahan

Sebelum pelaksanaan, perkhidmatan boleh menempah baki yang mencukupi untuk operasi. Kerja yang berjaya diselesaikan terhadap tempahan itu; kegagalan yang disahkan melepaskannya. Untuk tugas tak segerak, pemulangan ID tidak bermakna pengebilan sudah muktamad.

Pengebilan halaman PPT menempah sepuluh halaman semasa penciptaan. Penjanaan yang berjaya menyelesaikan output sebenar dan melepaskan dana yang tidak digunakan. Penjanaan dan eksport ialah caj berasingan. Lihat [aliran kerja PPT](https://openapi.felo.ai/ms/docs/data-api/guides/felo-ppt.md) untuk tingkah laku eksport berulang.

Jika pelaksanaan atau penyelesaian tidak pasti, tempahan boleh kekal menunggu sementara perkhidmatan menyelaraskannya. Jangan anggap setiap tamat masa atau 5xx sebagai bukti bahawa tiada kerja berlaku atau permintaan berulang adalah percuma.

Semak baki dan penggunaan anda yang tersedia dalam [Console Billing](https://openapi.felo.ai/console/billing). Untuk panduan tambah nilai pada tahap akaun, lihat [Pengebilan dan Kredit](https://openapi.felo.ai/ms/docs/faq/billing-and-credits.md).

## Dapatkan penggunaan dompet melalui API

Pemilik akaun boleh memeriksa rekod panggilan dompet menggunakan **token log masuk Felo**. Kredensial ini berbeza daripada Kunci API yang digunakan untuk panggilan Data API; jangan gantikan `FELO_API_KEY`.

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

Rekod berada di bawah `data.items`; `call_type=data` menapis panggilan keupayaan. Bandingkan penggunaan dengan harga semasa akaun. Membaca rekod tidak menghantar tugas penjanaan lain. Console Billing kekal tersedia untuk semakan akaun dan tambah nilai.

## Baca ralat secara defensif

Semak status HTTP terlebih dahulu. Ralat boleh menggunakan salah satu daripada bentuk ini; nilai di bawah adalah ilustratif:

```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"}
```

Baca `error.code` / `error.message` apabila ada, jika tidak `code` / `message`. Kekalkan `request_id` apabila dipulangkan. Respons berjaya berbeza mengikut operasi; jangan paksa semuanya ke dalam sampul ralat atau `data` yang sama.

## Tentukan tindakan seterusnya

| Status HTTP | Punca biasa | Langkah seterusnya |
|---|---|---|
| 400 | Parameter hilang atau tidak sah | Betulkan permintaan sebelum cuba semula |
| 401 | Kunci hilang, tidak sah, dibatalkan atau tamat tempoh | Semak kunci dan pengepala pengesahan |
| 402 | Baki platform tidak mencukupi | Semak baki tersedia dan tempahan yang belum selesai; tambah nilai jika perlu |
| 404 | Sumber tiada atau tidak boleh diakses oleh akaun ini | Semak ID dan akaun pencipta |
| 409 | Operasi bercanggah dengan keadaan tugas semasa, atau pelaksanaan tidak disahkan | Baca kod ralat dan lakukan pertanyaan pada tugas sedia ada; jangan gandakannya serta-merta |
| 410 | Sumber tamat tempoh atau dipadam | Gunakan fail yang disimpan; cipta tugas baharu hanya jika perlu |
| 429 | Had kadar atau kuota kunci API melebihi | Periksa maklumat tetapan semula; perlahan atau tunggu tetapan semula kuota |
| 502 / 503 / 504 | Huluan, ketersediaan, tamat masa atau kegagalan penyelesaian | Semak sama ada kerja sudah wujud sebelum cuba semula operasi berbayar |

`execution_unconfirmed` (409) dan `billing_settlement_pending` (503) memerlukan perhatian khas: jangan hantar semula kerja berbayar serta-merta. Lakukan pertanyaan pada tugas yang diketahui atau hubungi sokongan dengan ID permintaan. Status HTTP berjaya dengan hasil kosong adalah berbeza daripada respons ralat.

## Cuba semula tanpa mencipta kerja berganda

- Untuk pertanyaan status tugas dan status eksport yang hanya baca, gunakan backoff terhad dan patuhi `Retry-After` apabila ada.
- Untuk permintaan cipta yang gagal dengan `task_id` yang disimpan, lakukan pertanyaan pada tugas itu sebelum mencipta yang lain.
- Jika sambungan gagal sebelum anda menerima ID, hasilnya mungkin tidak diketahui. Jangan anggap bahawa menghantar semula akan menyahgandakan permintaan.
- Untuk 429, bezakan antara had kadar jangka pendek dan tetingkap kuota kunci API; cuba semula berulang kali tidak boleh menetapkan semula kuota.
- Hentikan percubaan semula selepas garis masa akhir yang dikonfigurasi dan tunjukkan ralat yang boleh diambil tindakan kepada pemanggil.

Untuk sokongan, berikan titik akhir, masa anggaran, status HTTP dan ID permintaan. Jangan sekali-kali sertakan keseluruhan kunci API.