# OpenAPI Penagihan dan Kesalahan

Pahami saldo platform, biaya permintaan dan hasil, penagihan per halaman, serta retry yang aman.

Halaman ini berlaku untuk `/api/v1/data/*`, API eksklusif platform OpenAPI Felo. Panggilan menggunakan **saldo platform**, saldo kredit layanan dalam denominasi USD. Ini tidak mengonsumsi kredit Felo Pro. [Felo APIs](https://openapi.felo.ai/id/docs/api-reference/felo-apis.md) yang lebih lama di bawah `/v2` menggunakan kredit Pro.

## Baca harga terkini

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

Endpoint publik ini tidak memerlukan kunci. Cocokkan entri berdasarkan ID operasi dan baca tarif serta unit penagihan saat ini; jangan mengasumsikan setiap operasi berbiaya sama atau membekukan tarif dari contoh ke aplikasi Anda.

| ID Operasi | Unit penagihan |
|---|---|
| `web.search`, `web.read`, `chat` | Permintaan |
| `x.user.info`, `x.user.search`, `x.user.tweets`, `x.tweet.search`, `x.tweet.replies` | Hasil yang dikembalikan |
| `ppt.generate` | Halaman yang dihasilkan |
| `ppt.export` | Permintaan ekspor |
| `ppt.generate.status`, `ppt.generate.historical`, `ppt.export.status`, `ppt.delete` | Tidak ada biaya baru |

Kueri status gratis tidak membuat pembuatan atau ekspor yang mendasarinya menjadi gratis. Untuk X, paginasi dan rekaman bersarang yang dikembalikan dapat meningkatkan penggunaan yang ditagihkan.

## Saldo dan reservasi

Sebelum eksekusi, layanan dapat mencadangkan saldo yang cukup untuk operasi tersebut. Pekerjaan yang sukses diselesaikan terhadap cadangan itu; kegagalan yang dikonfirmasi melepaskannya. Untuk tugas asinkron, mengembalikan ID tidak berarti penagihan sudah final.

Harga halaman PPT mencadangkan sepuluh halaman saat pembuatan. Pembuatan yang sukses menyelesaikan output aktual dan melepaskan dana yang tidak terpakai. Pembuatan dan ekspor adalah biaya yang terpisah. Lihat [alur kerja PPT](https://openapi.felo.ai/id/docs/data-api/guides/felo-ppt.md) untuk perilaku ekspor berulang.

Jika eksekusi atau penyelesaian tidak pasti, reservasi dapat tetap tertunda saat layanan merekonsiliasinya. Jangan perlakukan setiap timeout atau 5xx sebagai bukti bahwa tidak ada pekerjaan yang terjadi atau bahwa permintaan berulang itu gratis.

Tinjau saldo tersedia dan penggunaan Anda di [Console Billing](https://openapi.felo.ai/console/billing). Untuk panduan isi ulang di tingkat akun, lihat [Billing and Credits](https://openapi.felo.ai/id/docs/faq/billing-and-credits.md).

## Periksa penggunaan wallet melalui API

Pemilik akun dapat memeriksa catatan panggilan wallet menggunakan **Felo login token**. Kredensial ini berbeda dari API Key yang digunakan untuk panggilan Data API; jangan menggantikan `FELO_API_KEY`.

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

Catatan berada di bawah `data.items`; `call_type=data` memfilter panggilan kapabilitas. Bandingkan penggunaan dengan harga saat ini pada akun. Membaca catatan tidak mengirim tugas pembuatan lain. Console Billing tetap tersedia untuk peninjauan dan isi ulang akun.

## Baca kesalahan secara defensif

Periksa status HTTP terlebih dahulu. Kesalahan dapat menggunakan salah satu dari bentuk ini; nilai di bawah bersifat 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` jika ada, jika tidak `code` / `message`. Pertahankan `request_id` jika dikembalikan. Respons sukses bervariasi menurut operasi; jangan paksa semuanya ke dalam pembungkus error atau `data` yang sama.

## Putuskan tindakan berikutnya

| Status HTTP | Penyebab umum | Langkah berikutnya |
|---|---|---|
| 400 | Parameter hilang atau tidak valid | Perbaiki permintaan sebelum mencoba lagi |
| 401 | Kunci hilang, tidak valid, dicabut, atau kedaluwarsa | Periksa kunci dan header autentikasi |
| 402 | Saldo platform tidak cukup | Periksa saldo tersedia dan reservasi yang tertunda; isi ulang jika perlu |
| 404 | Resource hilang atau tidak dapat diakses oleh akun ini | Periksa ID dan akun pembuat |
| 409 | Operasi bentrok dengan status tugas saat ini, atau eksekusi belum dikonfirmasi | Baca kode kesalahan dan kueri tugas yang ada; jangan langsung menggandakannya |
| 410 | Resource kedaluwarsa atau dihapus | Gunakan file yang disimpan; buat tugas baru hanya jika perlu |
| 429 | Batas laju atau kuota API key terlampaui | Periksa informasi reset; perlambat atau tunggu reset kuota |
| 502 / 503 / 504 | Kegagalan upstream, ketersediaan, timeout, atau penyelesaian | Periksa apakah pekerjaan sudah ada sebelum mencoba lagi operasi berbayar |

`execution_unconfirmed` (409) dan `billing_settlement_pending` (503) memerlukan perhatian khusus: jangan langsung mengirim ulang pekerjaan berbayar. Kueri tugas yang diketahui atau hubungi dukungan dengan request ID. Status HTTP sukses dengan hasil kosong berbeda dari respons kesalahan.

## Retry tanpa membuat pekerjaan duplikat

- Untuk kueri tugas dan status ekspor yang hanya baca, gunakan backoff terbatas dan hormati `Retry-After` bila ada.
- Untuk permintaan create yang gagal dengan `task_id` tersimpan, kueri tugas itu sebelum membuat yang lain.
- Jika koneksi gagal sebelum Anda menerima ID, hasilnya mungkin tidak diketahui. Jangan mengasumsikan bahwa mengirim ulang akan menduplikasi permintaan.
- Untuk 429, bedakan batas laju singkat dari jendela kuota API key; retry berulang tidak dapat mereset kuota.
- Hentikan retry setelah tenggat yang dikonfigurasi dan tampilkan kesalahan yang dapat ditindaklanjuti kepada pemanggil.

Untuk dukungan, berikan endpoint, waktu perkiraan, status HTTP, dan request ID. Jangan pernah menyertakan API key penuh.