# การเรียกเก็บเงินและข้อผิดพลาดของ OpenAPI

ทำความเข้าใจยอดคงเหลือบนแพลตฟอร์ม ค่าบริการตามคำขอและผลลัพธ์ การเรียกเก็บเงินตามหน้า และกฎการลองใหม่อย่างปลอดภัย.

หน้านี้ใช้กับ `/api/v1/data/*`, Felo OpenAPI platform-exclusive APIs การเรียกใช้ใช้ **ยอดคงเหลือบนแพลตฟอร์ม** ซึ่งเป็นยอดเครดิตบริการที่กำหนดเป็น USD พวกมันไม่ใช้ Felo Pro credits [Felo APIs](https://openapi.felo.ai/th/docs/api-reference/felo-apis.md) แบบเก่าภายใต้ `/v2` ใช้ Pro credits

## อ่านราคาปัจจุบัน

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

เอนด์พอยต์สาธารณะนี้ไม่ต้องใช้ key จับคู่รายการด้วย operation ID และอ่านอัตราปัจจุบันกับหน่วยการเรียกเก็บเงิน; อย่าสมมติว่าทุก operation มีค่าใช้จ่ายเท่ากัน หรือคัดลอกอัตราจากตัวอย่างไปใช้ตรึงไว้ในแอปพลิเคชันของคุณ

| Operation 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` | ไม่มีการคิดค่าบริการใหม่ |

คำขอสถานะที่ไม่มีค่าบริการไม่ได้ทำให้การสร้างหรือการส่งออกที่อยู่เบื้องหลังไม่มีค่าบริการตามไปด้วย สำหรับ X การแบ่งหน้าและระเบียนที่ส่งคืนแบบซ้อนกันอาจเพิ่มการใช้งานที่คิดค่าบริการได้

## ยอดคงเหลือและการกันวงเงิน

ก่อนการดำเนินการ บริการสามารถกันยอดคงเหลือให้เพียงพอกับการทำงานได้ งานที่สำเร็จจะชำระตามวงเงินที่กันไว้; ความล้มเหลวที่ยืนยันแล้วจะปลดวงเงินออก สำหรับงานอะซิงโครนัส การส่งคืน ID ไม่ได้หมายความว่าการเรียกเก็บเงินได้ข้อสรุปแล้ว

การคิดค่าบริการตามหน้า PPT จะกันวงเงินสิบหน้าเมื่อสร้าง การสร้างที่สำเร็จจะชำระตามผลลัพธ์จริงและปลดเงินที่ไม่ได้ใช้ การสร้างและการส่งออกเป็นค่าบริการแยกกัน ดู [เวิร์กโฟลว์ PPT](https://openapi.felo.ai/th/docs/data-api/guides/felo-ppt.md) สำหรับพฤติกรรมการส่งออกซ้ำ

หากการดำเนินการหรือการชำระยอดไม่แน่นอน การกันวงเงินอาจค้างสถานะ pending ในขณะที่บริการกำลังปรับยอด อย่าถือว่า timeout หรือ 5xx ทุกครั้งเป็นหลักฐานว่าไม่มีงานเกิดขึ้น หรือคำขอที่ทำซ้ำจะไม่ถูกคิดค่าใช้จ่าย

ตรวจสอบยอดคงเหลือและการใช้งานของคุณใน [Console Billing](https://openapi.felo.ai/console/billing) สำหรับคำแนะนำการเติมเงินระดับบัญชี ดู [Billing and Credits](https://openapi.felo.ai/th/docs/faq/billing-and-credits.md)

## ตรวจสอบการใช้ wallet ผ่าน API

เจ้าของบัญชีสามารถตรวจสอบบันทึกการเรียกของ wallet ได้โดยใช้ **Felo login token** ข้อมูลรับรองนี้แตกต่างจาก API Key ที่ใช้สำหรับการเรียก Data API; อย่าใช้แทน `FELO_API_KEY`

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

บันทึกอยู่ภายใต้ `data.items`; `call_type=data` กรองการเรียกความสามารถ เปรียบเทียบการใช้งานกับราคาปัจจุบันของบัญชี การอ่านบันทึกไม่ได้ส่ง task การสร้างใหม่ Console Billing ยังใช้สำหรับตรวจสอบบัญชีและเติมเงินได้

## อ่านข้อผิดพลาดอย่างระมัดระวัง

ตรวจสอบ HTTP status ก่อน ข้อผิดพลาดอาจใช้รูปแบบใดรูปแบบหนึ่งต่อไปนี้; ค่าด้านล่างเป็นเพียงตัวอย่าง:

```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` ไว้เมื่อมีการส่งคืน การตอบกลับที่สำเร็จจะแตกต่างกันตามการทำงาน; อย่าบังคับให้ทุกอย่างอยู่ใน error หรือ `data` envelope เดียวกัน

## ตัดสินใจว่าจะทำอะไรต่อ

| HTTP status | สาเหตุทั่วไป | ขั้นตอนถัดไป |
|---|---|---|
| 400 | พารามิเตอร์หายไปหรือไม่ถูกต้อง | แก้คำขอก่อนลองใหม่ |
| 401 | key หายไป ไม่ถูกต้อง ถูกเพิกถอน หรือหมดอายุ | ตรวจสอบ key และ header การยืนยันตัวตน |
| 402 | ยอดคงเหลือบนแพลตฟอร์มไม่เพียงพอ | ตรวจสอบยอดคงเหลือที่พร้อมใช้และรายการกันวงเงินที่ค้างอยู่; เติมเงินหากจำเป็น |
| 404 | ทรัพยากรหายไปหรือบัญชีนี้เข้าถึงไม่ได้ | ตรวจสอบ ID และบัญชีที่สร้าง |
| 409 | การทำงานขัดกับสถานะ task ปัจจุบัน หรือยังยืนยันการดำเนินการไม่ได้ | อ่าน error code และโพล task ที่มีอยู่; อย่า duplicate ทันที |
| 410 | ทรัพยากรหมดอายุหรือลบแล้ว | ใช้ไฟล์ที่บันทึกไว้; สร้าง task ใหม่เฉพาะเมื่อจำเป็น |
| 429 | เกิน rate limit หรือเกิน quota ของ API key | ตรวจสอบข้อมูล reset; ลดความถี่หรือรอให้ quota รีเซ็ต |
| 502 / 503 / 504 | ความล้มเหลวจาก upstream, ความพร้อมใช้งาน, timeout หรือการชำระยอด | ตรวจสอบว่างานมีอยู่แล้วหรือไม่ก่อนลองใหม่กับการทำงานที่คิดค่าบริการ |

`execution_unconfirmed` (409) และ `billing_settlement_pending` (503) ต้องระมัดระวังเป็นพิเศษ: อย่าส่งงานที่คิดค่าบริการซ้ำทันที ให้โพล task ที่ทราบอยู่แล้วหรือแจ้งซัพพอร์ตพร้อม request ID อย่าสับสนระหว่าง HTTP status ที่สำเร็จแต่ผลลัพธ์ว่าง กับ response ข้อผิดพลาด

## ลองใหม่โดยไม่สร้างงานซ้ำ

- สำหรับคำขออ่านอย่างเดียวและคำขอสถานะการส่งออก ให้ใช้ backoff แบบจำกัดและเคารพ `Retry-After` เมื่อมี
- สำหรับคำขอ create ที่ล้มเหลวโดยมี `task_id` ที่บันทึกไว้ ให้โพล task นั้นก่อนสร้างอันใหม่
- หากการเชื่อมต่อล้มเหลวก่อนที่คุณจะได้รับ ID ผลลัพธ์อาจไม่แน่ชัด อย่าสมมติว่าการส่งซ้ำจะ deduplicate คำขอ
- สำหรับ 429 ให้แยกความแตกต่างระหว่าง rate limit ระยะสั้นกับหน้าต่าง quota ของ API key; การลองซ้ำบ่อยๆ ไม่สามารถรีเซ็ต quota ได้
- หยุดลองใหม่หลังเส้นตายที่ตั้งค่าไว้ และแสดงข้อผิดพลาดที่ดำเนินการต่อได้แก่ผู้เรียก

สำหรับการขอรับความช่วยเหลือ ให้ระบุเอนด์พอยต์ เวลาประมาณ HTTP status และ request ID อย่าใส่ API key แบบเต็ม