สิ่งที่ไม่คิดค่าบริการ: รหัสข้อผิดพลาดและกฎการเรียกเก็บเงิน
รายละเอียดกฎการเรียกเก็บเงินตามรหัสสถานะ HTTP, ข้อผิดพลาด JSON-RPC และ Data API พร้อมการดำเนินการที่แนะนำสำหรับนักพัฒนา
BlockVectra วัดปริมาณคำขอในหน่วย Compute Units (CU) โดยการเรียก JSON-RPC และ Data API จะถูกคิดค่าบริการหลังจากได้รับคำตอบกลับแล้วเท่านั้น คู่มือนี้สรุปกฎการพิจารณาการเรียกเก็บเงินตามรหัสสถานะ HTTP, การเรียก JSON-RPC และ Data API พร้อมการดำเนินการที่แนะนำสำหรับนักพัฒนา
รหัสสถานะ HTTP และกฎการเรียกเก็บเงิน
กฎการพิจารณาการเรียกเก็บเงินและการจัดการสำหรับการตอบกลับในระดับ HTTP มีดังนี้:
| สถานะ HTTP | บอดีการตอบกลับ | สถานการณ์ | คิดค่าบริการหรือไม่? | การดำเนินการที่แนะนำ |
|---|---|---|---|---|
| 200 | การตอบกลับ JSON-RPC (เดี่ยวหรือแบบชุด) | การตอบกลับปกติ; ข้อผิดพลาดในระดับชั้น JSON-RPC ทั้งหมด (ข้อผิดพลาดการแจงส่วน, การปฏิเสธเมธอด, อัปสตรีมล้มเหลว, ข้อผิดพลาดของโหนด) ก็เป็น 200 เช่นกัน | ประเมินแยกตามการเรียก | ตรวจสอบ result หรือ error ในแต่ละการเรียก; หากส่งคืนข้อผิดพลาด โปรดดูการจัดการข้อผิดพลาด JSON-RPC ด้านล่าง |
| 204 | ว่างเปล่า | ทุกการเรียกในคำขอเป็นการแจ้งเตือน (notifications) | การแจ้งเตือนจะถูกคิดค่าบริการตามปกติ | ไม่ต้องดำเนินการเพิ่มเติม |
| 400 | ว่างเปล่า | ข้อความ HTTP มีรูปแบบไม่ถูกต้อง (ไม่สามารถแจงส่วนบรรทัดคำขอหรือส่วนหัวได้, การเข้ารหัส chunked ไม่ถูกต้อง) หรือระยะเวลาระหว่างการอ่านบอดีคำขอสองครั้งเกิน 10 วินาที | ไม่ | ตรวจสอบไวยากรณ์คำขอ HTTP, ส่วนหัว และความต่อเนื่องของการส่งข้อมูล |
| 402 | JSON, -32020 | ยอดคงเหลือไม่เพียงพอ, โควตาหมดลง; เมื่อทราบยอดคงเหลือ error.data จะรวม balance_units และ balance_cu | ไม่ | ตรวจสอบยอดคงเหลือของคุณใน หน้า Billing ของคอนโซล หรือผ่าน GET /v1/topup/deposit-address (MCP get_deposit_address); เติมเงินบนเชนไปยังที่อยู่เฉพาะของบัญชีคุณ (ดู คู่มือการเติมเงินของ Agent) |
| 403 | ว่างเปล่า | เมธอดอื่นนอกเหนือจาก POST หรือ OPTIONS บน /v1/{chain} หรือ /v1/{chain}/{api_key} (ไม่ว่าชื่อเชนจะเป็นที่รู้จักหรือไม่ก็ตาม) | ไม่ | เปลี่ยนเมธอดคำขอ HTTP เป็น POST (หรือ cross-origin OPTIONS preflight) |
| 401 | JSON, -32024 (missing_api_key หรือ invalid_api_key) | ไม่มีคีย์บนเชนที่รู้จัก, คีย์ไม่รู้จัก หรือถูกปิดใช้งาน | ไม่ | ส่ง API key ที่ใช้งานได้ในส่วนหัว x-api-key (คีย์ที่สร้างใหม่หรือเพิ่งหมุนเวียนต้องใช้เวลาสองสามวินาทีจึงจะมีผล; ให้รอสักครู่แล้วลองใหม่) |
| 404 | JSON, -32600 (reason = unknown_chain) | POST ไปยัง {chain} ที่ไม่รู้จัก | ไม่ | ตรวจสอบชื่อเชนใน URL เทียบกับ เชนที่รองรับ (ต้องเป็นสลักตัวพิมพ์เล็กตรงกันทุกประการ) |
| 404 | บอดีว่างเปล่า (empty body) | พาธไม่ตรงกัน (เช่น POST /v1, /v1/, POST /v1/{chain}/) | ไม่ | ใส่เชนใน URL (/v1/{chain}) |
| 408 | ว่างเปล่า | ใช้เวลาเกิน 35 วินาทีจากการอ่านส่วนหัวคำขอจนถึงการส่งคืนการตอบกลับ | เป็นไปได้: การเรียกที่ส่งต่อไปยังโหนดแล้วจะถูกคิดค่าบริการตามปกติเมื่อโหนดตอบกลับ | อย่าลองใหม่สำหรับการเรียกที่เปลี่ยนสถานะ (เช่น eth_sendRawTransaction) โดยไม่มีเงื่อนไข; การตัดการเชื่อมต่อของไคลเอนต์ไม่ได้ยกเลิกการเรียกที่ส่งต่อไปแล้ว |
| 413 | ว่างเปล่า | บอดีคำขอ > 2 MiB (2,097,152 ไบต์; ดู “10. Limits at a glance” ใน ข้อมูลอ้างอิง OpenAPI ฉบับสมบูรณ์) | ไม่ | ควบคุมบอดีคำขอให้ต่ำกว่า 2 MiB; แยกชุดคำขอออกเป็นคำขอย่อยๆ |
| 414 / 431 | ว่างเปล่า | URI ยาวเกินไป (414) หรือส่วนหัวคำขอมีขนาดใหญ่เกินไป (431) | ไม่ | ย่อ URI คำขอให้สั้นลง หรือตัดส่วนหัวคำขอ HTTP |
| 429 | JSON, -32005 หรือ -32022; มี Retry-After สำหรับการจำกัดอัตรา (-32005); ขีดจำกัด burst/ขนาดชุด (-32022) จะไม่มีส่วนหัวนี้ | ยอดคงเหลือในบักเก็ตหมด → -32005; CU คำขอเดี่ยวเกินความจุ burst → -32022; ขีดจำกัดอัตราการเรียกของบัญชีหมด → -32005; จำนวนการเรียกในคำขอเดี่ยวเกินขีดจำกัด → -32022 | ไม่ | สำหรับ -32005 ที่มี Retry-After ให้รอตามจำนวนวินาทีที่ระบุก่อนลองใหม่; สำหรับ -32022 ให้แยกคำขอหรือลดขนาดชุด (การลองใหม่โดยไม่แก้ไขจะไม่มีทางสำเร็จ) |
| 503 | JSON, -32021 พร้อม Retry-After | ข้อมูลการเรียกเก็บเงินไม่พร้อมใช้งานชั่วคราว; เซิร์ฟเวอร์ปฏิเสธคำขอชั่วคราว (ไม่ใช่ปัญหายอดคงเหลือ ไม่จำเป็นต้องเติมเงิน); คีย์ที่สร้างใหม่จะส่งคืนค่านี้จนกว่าข้อมูลการเรียกเก็บเงินจะซิงค์ (โดยปกติใช้เวลาสองสามวินาที) | ไม่ | ไม่ใช่ปัญหายอดคงเหลือ ไม่จำเป็นต้องเติมเงิน; รอตามจำนวนวินาทีที่ระบุใน Retry-After แล้วลองใหม่ |
หมายเหตุ: เมื่อเข้าถึงผ่าน Cloudflare ทาง Cloudflare อาจส่งคืนหน้าข้อผิดพลาด 52x หรือ 1015 ซึ่งไม่ได้สร้างขึ้นโดยบริการ
ส่วนหัวการตอบกลับสำหรับการคิดค่าบริการและยอดคงเหลือ: เมื่อส่ง
x-bv-meter: 1ในคำขอ HTTP (ใช้ได้ทั้ง JSON-RPC และ Data API) การตอบกลับที่มีการคิดค่าบริการอย่างน้อยหนึ่งการเรียกจะส่งคืนx-bv-cu-charged(Compute Units ที่คิดค่าบริการสำหรับคำขอนี้ หรือผลรวมของการเรียกที่คิดค่าบริการในชุด) และx-bv-balance-units(หน่วยยอดคงเหลือที่เหลืออยู่ในบัญชีทันทีหลังจากการคิดค่าบริการนี้ ซึ่งอาจติดลบได้หากใช้เกิน; จะละเว้นหากไม่ทราบยอดคงเหลือ) คำขอที่ไม่มีx-bv-meter: 1, การตอบกลับที่ไม่มีการคิดค่าบริการใดๆ และการตอบกลับข้อผิดพลาด 402, 403, 429 หรือ 503 จะละเว้นส่วนหัวทั้งสองนี้ ส่วนหัวการตอบกลับเหล่านี้สามารถเข้าถึงได้โดยสคริปต์เบราว์เซอร์ผ่าน CORS ในขณะที่ WebSocket จะไม่ใช้ส่วนหัวเหล่านี้ ยอดคงเหลือจะหักการใช้งานที่ยังไม่ได้ชำระทั้งหมดโดยปัดเศษขึ้นเป็นหน่วยเต็มหนึ่งครั้ง; การสรุปยอดรายชั่วโมงจะปัดเศษลง ดังนั้นยอดคงเหลือที่รายงานอาจเพิ่มขึ้นสูงสุดหนึ่งหน่วยหลังจากการสรุปยอด
รหัสข้อผิดพลาด JSON-RPC และกฎการเรียกเก็บเงิน
รหัสข้อผิดพลาดเดียวกันอาจมาจากแพลตฟอร์มหรือโหนด และการเรียกเก็บเงินจะแตกต่างกัน:
- ข้อผิดพลาดที่สร้างขึ้นโดยตัวแพลตฟอร์มเอง: จะไม่คิดค่าบริการเสมอ
- ข้อผิดพลาดที่ส่งคืนโดยโหนด: จะถูกส่งต่อตามที่เป็นและคิดค่าบริการตามน้ำหนักของเมธอด โดยมีข้อยกเว้นเฉพาะรหัสข้อผิดพลาดของโหนดที่ระบุด้านล่างเท่านั้น
รายละเอียดกฎ
- ข้อผิดพลาดของโหนดที่ไม่คิดค่าบริการ:
-32002(batch timeout),-32003(batch response too large) และ-32600(batch rejected as a whole) ของโหนด บ่งชี้ว่าโหนดละทิ้งการเรียกก่อนกำหนด; ข้อผิดพลาดเหล่านี้รวมถึงการแจ้งเตือน (notifications) ใดๆ ในชุดเดียวกันจะไม่ถูกคิดค่าบริการ ส่วน-32601(exposed method not implemented) และ-32603(node internal failure) ของโหนด จะไม่คิดค่าบริการผ่าน HTTP หรือ WebSocket และไม่ส่งผลกระทบต่อการเรียกหรือการแจ้งเตือนอื่นๆ ในชุด นอกจากนี้4444(pruned block) และ-32000(สถานะย้อนหลังอยู่นอกหน้าต่างประวัติสถานะของโหนด ซึ่งกำหนดโดยstate_window_blocksในGET /v1/chains) จะไม่คิดค่าบริการและไม่ส่งผลต่อการเรียกอื่นๆ ในชุด - ข้อผิดพลาดของโหนดที่คิดค่าบริการ: ข้อผิดพลาดอื่นๆ ที่ส่งคืนโดยโหนดจะถูกคิดค่าบริการตามน้ำหนักของเมธอดเมื่อเป็นการรายงานผลลัพธ์ของเชน เช่น
execution reverted(-32000หรือ3พร้อมdata),-32602 invalid argumentของตัวโหนดเอง - การยอมรับยอดคงเหลือและการซิงค์:
-32020ระบุว่ายอดคงเหลือในบัญชีไม่เพียงพอและจำเป็นต้องเติมเงิน; เมื่อทราบยอดคงเหลือerror.data.balance_unitsและerror.data.balance_cuจะระบุจำนวนที่เหลืออยู่ (อาจติดลบได้) คีย์ที่สร้างใหม่อาจส่งคืน-32021(503) เป็นเวลาสองสามวินาที; ให้รอตามRetry-Afterแล้วลองใหม่ - ความล้มเหลวของอัปสตรีม:
-32603ที่สร้างโดยแพลตฟอร์มเนื่องจากการสื่อสารกับอัปสตรีมล้มเหลวหรือการตอบกลับมีรูปแบบไม่ถูกต้อง (upstream unavailable,no response from upstream,malformed upstream response) จะมีdata.reason: upstream_unavailable - การคิดค่าบริการการแจ้งเตือน: การแจ้งเตือน (Notifications 204) จะถูกคิดค่าบริการตามน้ำหนักของเมธอด
ตารางรหัสข้อผิดพลาด JSON-RPC
| รหัส | แหล่งที่มา | HTTP | ข้อความ | เหตุผล | คิดค่าบริการหรือไม่? | การดำเนินการที่แนะนำ |
|---|---|---|---|---|---|---|
| -32700 | BlockVectra | 200 | parse error | - | ไม่ (ใช้ 1 CU โทเค็นจำกัดอัตรา; ดู “9. Rate limiting” ใน ข้อมูลอ้างอิง OpenAPI ฉบับสมบูรณ์) | แก้ไขไวยากรณ์ JSON ของคำขอ |
| -32600 | BlockVectra | 200 | invalid request | invalid_request | ไม่ (ใช้ 1 CU โทเค็นจำกัดอัตรา; ดู “9. Rate limiting” ใน ข้อมูลอ้างอิง OpenAPI ฉบับสมบูรณ์) | แก้ไขไวยากรณ์และโครงสร้างคำขอ JSON-RPC |
| -32600 | BlockVectra | 200 | batch too large: max <N> calls | batch_too_large (+max) | ไม่ | แยกชุดคำขอให้มีจำนวนการเรียกต่ำกว่าขีดจำกัด (ขีดจำกัดชุดมาตรฐานคือ 100) |
| -32600 | BlockVectra | 200 | invalid request: ambiguous member name | invalid_request | ไม่ | ลบชื่อสมาชิกที่ซ้ำกันหรือไม่ชัดเจนในออบเจกต์ JSON |
| -32601 | BlockVectra | 200 | method not available: <method> | - | ไม่ | เรียกใช้เฉพาะเมธอดที่อนุญาตสำหรับเชนนี้เท่านั้น (ดู เชนที่รองรับ) |
| -32600 | BlockVectra | 404 | unknown chain | unknown_chain | ไม่ | ตรวจสอบชื่อเชนใน URL |
| -32602 | BlockVectra | 200 | eth_getLogs block range too large: max <N> blocks | - | ไม่ | ย่อช่วงบล็อกของ eth_getLogs ให้แคบลง (ขีดจำกัดกำหนดแยกตามเชน เช่น 1000 บล็อก) |
| -32602 | BlockVectra | 200 | tracer not allowed | - | ไม่ | ใช้ native tracer ที่ได้รับอนุญาต (callTracer, flatCallTracer, prestateTracer, 4byteTracer, noopTracer หรือละเว้น) |
| -32602 | BlockVectra | 200 | trace timeout not allowed | - | ไม่ | กำหนดสตริง Go duration ที่ถูกต้องโดยมี timeout ≤ 30s |
| -32010 | BlockVectra | 200 | node is syncing; calls are temporarily unavailable | - | ไม่ | โหนดกำลังซิงค์ ลองใหม่ในภายหลัง (ยกเว้น eth_chainId) |
| -32011 | BlockVectra | 200 | historical state is not available beyond the most recent <N> blocks | - | ไม่ | สืบค้นบล็อกที่เป็นปัจจุบันมากขึ้น (บล็อกเป้าหมายต้องอยู่ภายในหน้าต่างสถานะ; หลีกเลี่ยงแท็ก safe/finalized/earliest) |
| -32000 | BlockVectra | 200 | transaction not found | not_found | ไม่ | ตรวจสอบแฮชธุรกรรม (0x + 64 อักขระฐานสิบหก) |
| -32000 | BlockVectra | 200 | block not found | not_found | ไม่ | ตรวจสอบแฮชหรือหมายเลขบล็อก |
| -32000 | BlockVectra | 200 | upstream response too large | response_too_large | ไม่ | จำกัดขอบเขตการสืบค้นให้แคบลงหรือแยกคำขอ |
| -32005 | BlockVectra | 200 | - | overloaded | ไม่ | เซิร์ฟเวอร์ทำงานหนักเกินไปชั่วคราว ลองใหม่ในภายหลัง |
| -32005 | BlockVectra | 429 | rate limit exceeded | key_rate_limit / free_plan_call_limit / concurrency_limit | ไม่ | ลดความถี่ของคำขอ; ปฏิบัติตาม Retry-After เมื่อมีระบุ |
| -32022 | BlockVectra | 429 | request cost <N> CU exceeds burst capacity <M> CU | request_exceeds_burst | ไม่ | แยกคำขอหรือชุดคำขอเพื่อให้ CU ของคำขอเดี่ยวต่ำกว่าความจุ burst |
| -32022 | BlockVectra | 429 | request has <N> calls, exceeding the free-plan limit of <M> calls per second | free_plan_batch_too_large (+max) | ไม่ | แยกชุดคำขอให้อยู่ภายใต้ขีดจำกัดต่อวินาที หรืออัปเกรดเป็นแพ็กเกจชำระเงิน |
| -32603 | BlockVectra | 200 | upstream unavailable | upstream_unavailable | ไม่ | การสื่อสารกับอัปสตรีมล้มเหลว ลองใหม่ในภายหลัง |
| -32603 | BlockVectra | 200 | no response from upstream | upstream_unavailable | ไม่ | อัปสตรีมไม่ตอบสนอง ลองใหม่ในภายหลัง |
| -32603 | BlockVectra | 200 | malformed upstream response | upstream_unavailable | ไม่ | การตอบกลับของอัปสตรีมมีรูปแบบไม่ถูกต้อง ลองใหม่ในภายหลัง |
| -32603 | BlockVectra | 200 | - | - | ไม่ | ข้อผิดพลาดภายในที่เกิดขึ้นไม่บ่อย ลองใหม่ในภายหลัง |
| -32020 | BlockVectra | 402 | insufficient balance | balance_exhausted / free_grant_exhausted (+topup_url และ +balance_units / balance_cu เมื่อทราบยอดคงเหลือ) | ไม่ | ตรวจสอบยอดคงเหลือของคุณใน หน้า Billing ของคอนโซล หรือผ่าน GET /v1/topup/deposit-address (MCP get_deposit_address); เติมเงินบนเชนไปยังที่อยู่เฉพาะของบัญชีคุณ (ดู คู่มือการเติมเงินของ Agent) |
| -32021 | BlockVectra | 503 | billing data temporarily unavailable | - | ไม่ | ข้อมูลการเรียกเก็บเงินกำลังซิงค์ (ไม่ใช่ปัญหายอดคงเหลือ); รอตามวินาทีของ Retry-After แล้วลองใหม่ |
| 4444 | Node | 200 | pruned history unavailable | - | ไม่ | บล็อกที่ร้องขอถูกตัดตอน (pruned) โดยโหนด; ไม่คิดค่าบริการ; ไม่ส่งผลต่อชุดคำขอ |
| -32000 | Node | 200 | historical state ... is not available | - | ไม่ | อยู่นอกหน้าต่างประวัติสถานะของโหนด; ไม่คิดค่าบริการ; ไม่ส่งผลต่อชุดคำขอ |
| -32000 | Node | 200 | old data not available due to pruning... | - | ไม่ | อยู่นอกหน้าต่างประวัติของโหนด (หน้าต่างกำหนดโดย state_window_blocks); ไม่คิดค่าบริการ; ไม่ส่งผลต่อชุดคำขอ |
| -32002 | Node | 200 | <node message> | - | ไม่ | โหนดหมดเวลาในชุดคำขอและละทิ้งการเรียก; ไม่คิดค่าบริการ; การแจ้งเตือนในชุดก็ไม่คิดค่าบริการเช่นกัน |
| -32003 | Node | 200 | <node message> | - | ไม่ | การตอบกลับชุดคำขอของโหนดมีขนาดใหญ่เกินไปและถูกละทิ้ง; ไม่คิดค่าบริการ; การแจ้งเตือนในชุดก็ไม่คิดค่าบริการเช่นกัน |
| -32601 | Node | 200 | <node message> | - | ไม่ | เมธอดที่เปิดเผยไม่ได้ถูกนำไปใช้งานโดยโหนด; ให้ใช้เมธอดอื่นที่รองรับ |
| -32603 | Node | 200 | <node message> | - | ไม่ | ความล้มเหลวภายในของโหนด; ให้ลองใหม่พร้อม backoff |
| -32600 | Node | 200 | <node message> | - | ไม่ | ทั้งชุดคำขอถูกปฏิเสธโดยโหนด; ไม่คิดค่าบริการ; การแจ้งเตือนในชุดก็ไม่คิดค่าบริการเช่นกัน |
| อื่นๆ | Node | 200 | <node message> | - | คิดค่าบริการ (ตามน้ำหนักของเมธอด) | ผลลัพธ์ของเชน (เช่น execution reverted, -32602 ของโหนด); ตรวจสอบพารามิเตอร์การเรียกสัญญา |
กฎการเรียกเก็บเงินของ Data API
Data API ห่อหุ้มข้อมูลเชนแบบอ่านอย่างเดียวไว้ใน REST endpoint โดยการคิดค่าบริการและการจัดการข้อผิดพลาดจะเป็นไปตามกฎเหล่านี้:
รายละเอียดกฎ
- คิดค่าบริการเฉพาะการตอบกลับที่สำเร็จระดับ 2xx เท่านั้น
- การดำเนินการที่ไม่พร้อมใช้งานซึ่งอยู่นอกเหนือความครอบคลุม (เช่น เชนที่ไม่รองรับ หรือบล็อกที่อยู่นอกความครอบคลุมของ trace) จะส่งคืน HTTP 422
no_coverageซึ่งไม่คิดค่าบริการแต่นับรวมในขีดจำกัดอัตรา - การตอบกลับ HTTP 401, 402, 404 และ 429 ไม่คิดค่าบริการ สำหรับส่วนหัวการตอบกลับ (
x-bv-meter: 1) โปรดดู รหัสสถานะ HTTP และกฎการเรียกเก็บเงิน
ตารางรหัสสถานะ Data API
| สถานะ HTTP | รหัสข้อผิดพลาด / สถานการณ์ | คิดค่าบริการหรือไม่? | การดำเนินการที่แนะนำ |
|---|---|---|---|
| 200 | การตอบกลับข้อมูลสำเร็จ | คิดค่าบริการ (ตามน้ำหนัก CU ของการดำเนินการ Data API) | แจงส่วน data, meta และ next_cursor ใน envelope ของการตอบกลับ |
| 400 | พารามิเตอร์คำขอมีรูปแบบไม่ถูกต้องหรือขาดฟิลด์ที่จำเป็น | ไม่ | ตรวจสอบและแก้ไขพารามิเตอร์ query หรือ body |
| 402 | ยอดคงเหลือหมด (error.code: "insufficient_balance" รวม balance_units และ balance_cu เมื่อทราบยอดคงเหลือ) | ไม่ | ตรวจสอบยอดคงเหลือของคุณใน หน้า Billing ของคอนโซล หรือผ่าน GET /v1/topup/deposit-address (MCP get_deposit_address); เติมเงินบนเชนไปยังที่อยู่เฉพาะของบัญชีคุณ (ดู คู่มือการเติมเงินของ Agent) |
| 401 | ไม่มี API key, คีย์ไม่รู้จัก หรือถูกปิดใช้งาน (error.code: "missing_api_key" หรือ "invalid_api_key") | ไม่ | ส่ง API key ที่ใช้งานได้ในส่วนหัว x-api-key |
| 404 | เชนไม่รู้จักหรือไม่ใช่สาธารณะ (error.code: "not_found") หรือออบเจกต์ที่ร้องขอไม่มีอยู่ | ไม่ | ตรวจสอบสลักเชนใน URL (ต้องเป็นตัวพิมพ์เล็กตรงกันทุกประการ) และพาธคำขอ |
| 409 | บล็อกหรือหน้าต่างที่ร้องขอสูงกว่าความสูงที่จัดทำดัชนีในปัจจุบัน (error.code: "not_indexed_yet" รวม indexed_through) | ไม่ | สืบค้นบล็อกได้สูงสุดถึง indexed_through หรือลองใหม่ในภายหลัง |
| 422 | การดำเนินการเฉพาะเชนไม่พร้อมใช้งาน (เช่น เชนที่ไม่รองรับ หรืออยู่นอกความครอบคลุมของ trace, error.code: "no_coverage") | ไม่ (นับรวมในขีดจำกัดอัตรา) | ตรวจสอบฟีเจอร์ที่รองรับผ่าน GET /v1/status (ฟรี, data_features แบบไม่ใช้คีย์) |
| 429 | เกินขีดจำกัดอัตรา (error.code: "rate_limited") หรือคำขอเดี่ยวมีค่าใช้จ่ายมากกว่าความจุ burst ของคีย์ (error.code: "cost_exceeds_burst") | ไม่ | ลดความถี่ของคำขอ; แยกคำขอที่มีขนาดใหญ่เกินไป (คำขอที่เกินความจุ burst จะไม่มีทางสำเร็จหากส่งในรูปแบบเดิม) |
| 503 | บริการข้อมูลไม่พร้อมใช้งานชั่วคราว (error.code: "unavailable") หรือเชนไม่ว่าง (error.code: "gateway_overloaded") | ไม่ | ลองใหม่ในภายหลังและปฏิบัติตาม Retry-After เมื่อมีระบุ |
ตรวจสอบยอดคงเหลือ (GET /v1/account)
ผู้ถือ API key สามารถตรวจสอบยอดคงเหลือและรายละเอียดโควตาของคีย์ได้โดยตรง โดยไม่มีค่าใช้จ่ายหรือหัก Compute Units (CU) ใดๆ:
curl -H "x-api-key: $BLOCKVECTRA_API_KEY" https://api.blockvectra.com/v1/account- ฟรีและไม่คิดค่าบริการ:
GET /v1/accountเป็นบริการฟรี จะไม่ถูกคิดค่าบริการ ไม่หัก CU และส่งคืน HTTP 200 พร้อมยอดคงเหลือปัจจุบันแม้ว่าจะเป็นศูนย์หรือติดลบก็ตาม (ไม่มีทางส่งคืน 402) - การยืนยันตัวตน: การยืนยันตัวตนด้วยคีย์จะใช้ส่วนหัว
x-api-keyเท่านั้น (ไม่รับคีย์ในพาธและ Bearer token) หากไม่มีส่วนหัวจะส่งคืน 401missing_api_key; คีย์ที่ไม่ถูกต้องหรือถูกเพิกถอนจะส่งคืน 401invalid_api_key(คีย์ที่หมดอายุจะส่งคืน 403key_expired; บริการที่ไม่พร้อมใช้งานชั่วคราวจะส่งคืน 503auth_unavailableหรือbilling_unavailableพร้อมRetry-After) - การจำกัดอัตรา: มีขีดจำกัดอิสระที่ 5 คำขอต่อวินาทีต่อ key ID โดยไม่ขึ้นกับการวัดปริมาณและการเรียกเก็บเงินของ CU การส่งคำขอเกินขีดจำกัดจะส่งคืน HTTP 429
rate_limitedพร้อมส่วนหัวRetry-After(ดู “10. Limits at a glance” ใน ข้อมูลอ้างอิง OpenAPI ฉบับสมบูรณ์)
ฟิลด์การตอบกลับ:
key_id: สตริงตัวระบุของ API keyplan: ประเภทแพ็กเกจของบัญชี (freeเมื่อบัญชีมีโควตาอัตราการเรียกของแพ็กเกจฟรี; นอกนั้นเป็นpaid)balance_units: ยอดคงเหลือในบัญชีที่เหลืออยู่ในหน่วย units (อาจเป็นศูนย์หรือติดลบได้)balance_cu: ยอดคงเหลือที่แปลงเป็น Compute Units (CU)balance_as_of_age_ms: มิลลิวินาทีที่ผ่านไปนับตั้งแต่การอ่านยอดคงเหลือจากแหล่งข้อมูลkey: ขีดจำกัดเฉพาะของคีย์และรายละเอียดโควตา:cu_per_sec: อัตราการเติม token-bucket ในหน่วย CU ต่อวินาทีburst_cu: ความจุ burst ของ token-bucket ในหน่วย CUcu_cap: เพดาน CU ตลอดอายุการใช้งานสำหรับคีย์นี้ หรือnullหากไม่ได้จำกัดเพดานcu_cap_remaining: CU ที่เหลืออยู่ภายใต้cu_capหรือnullหากไม่ได้จำกัดเพดาน (อาจเป็นศูนย์หรือติดลบได้)expires_at: การประทับเวลาหมดอายุตาม RFC 3339 หรือnullหากคีย์ไม่มีวันหมดอายุ
ตัวอย่างการตอบกลับ:
{
"key_id": "<key_id>",
"plan": "<plan>",
"balance_units": <integer>,
"balance_cu": <integer>,
"balance_as_of_age_ms": <integer>,
"key": {
"cu_per_sec": <integer>,
"burst_cu": <integer>,
"cu_cap": <integer_or_null>,
"cu_cap_remaining": <integer_or_null>,
"expires_at": "<expires_at_or_null>"
}
}การกำหนดราคาและการอัปเกรด
ค่าใช้จ่ายเฉพาะสำหรับการเรียกที่คิดค่าบริการทั้งหมดจะพิจารณาจากน้ำหนัก CU ที่ประกาศไว้:
- หากต้องการตรวจสอบน้ำหนักของเมธอดและการดำเนินการทั้งหมด โปรดดู ตารางน้ำหนักเมธอด และ กฎการวัดปริมาณ CU ของ JSON-RPC
- สำหรับรายละเอียดราคาของแพ็กเกจและการสรุปยอด โปรดดู หน้าราคา
- การอัปเกรดเป็นแพ็กเกจชำระเงิน: การเติมเงินแบบชำระเงินจะยกเลิกขีดจำกัดการเรียกต่อวินาทีของแพ็กเกจฟรี โดยแต่ละคีย์ยังคงอยู่ภายใต้อัตรา CU และขีดจำกัด burst
กระบวนการเติมเงินบนเชน
เมื่อยอดคงเหลือในบัญชีของคุณไม่เพียงพอหรือคุณต้องการ throughput ที่สูงขึ้น ให้เติมเงินบนเชนในคอนโซลตามขั้นตอนเหล่านี้:
- เข้าสู่ระบบคอนโซล: ลงชื่อเข้าใช้ BlockVectra Console
- ไปที่หน้า Billing: นำทางไปยัง หน้า Billing
- รับที่อยู่เฉพาะของคุณ: ในการ์ดการเติมเงินบนเชน ให้คัดลอกที่อยู่การเติมเงินเฉพาะของบัญชีคุณหรือสแกนคิวอาร์โค้ด
- โอนเงิน: โอนเงินโดยใช้เครือข่ายและ USDC / USDT / USDG ที่รองรับตามที่ระบุไว้ในหน้าดังกล่าวเท่านั้น เครือข่ายที่รองรับและจำนวนเงินเติมขั้นต่ำจะแสดงอยู่ในคอนโซล
- บันทึกเครดิตอัตโนมัติ: เมื่อตรวจพบบนเชนแล้ว ธุรกรรมจะแสดงสถานะเป็น "Processing"; และเมื่อบันทึกเครดิตแล้ว เครดิตจะถูกเพิ่มเข้าสู่ยอดคงเหลือของคุณโดยอัตโนมัติ
ข้อควรระวังสำคัญ:
- ใช้เฉพาะเครือข่ายและโทเค็นที่ระบุไว้อย่างชัดเจนในคอนโซลเท่านั้น การโอนบนเชนที่ไม่รองรับหรือใช้โทเค็นที่ไม่ถูกต้องจะไม่สามารถบันทึกเครดิตโดยอัตโนมัติได้
- ตรวจสอบให้แน่ใจว่าการโอนแต่ละครั้งมียอดถึงจำนวนเติมเงินขั้นต่ำที่ระบุไว้ในคอนโซล
- เมื่อการเติมเงินแบบชำระเงินครั้งแรกได้รับการบันทึกเครดิตแล้ว บัญชีของคุณจะได้รับการอัปเกรดเป็นบัญชีชำระเงิน ซึ่งจะยกเลิกขีดจำกัดการเรียกต่อวินาทีของแพ็กเกจฟรี
โปรแกรม Agent หรือเซิร์ฟเวอร์สามารถเรียก endpoint การเติมเงินได้โดยตรงโดยใช้ API key; ดูที่ คู่มือการเติมเงินแบบเป็นโปรแกรมของ Agent
การคิดค่าบริการ Webhook Push
บริการ Push มีน้ำหนักแยกต่างหากสำหรับอีเวนต์ข้อมูลที่ส่งมอบสำเร็จ, การสืบค้นประวัติที่สำเร็จ และ address-days ที่คิดค่าบริการได้ การเรียกการจัดการนอกเหนือจากประวัติอีเวนต์, ความพยายามส่งมอบที่ล้มเหลว, การลองใหม่อัตโนมัติ และอีเวนต์ควบคุมจะไม่มีค่าบริการ อีเวนต์ที่ส่งมอบแต่ละรายการจะถูกคิดค่าบริการครั้งเดียว; การเล่นซ้ำของลูกค้าและอีเวนต์ตามสายหลัก (canonical events) ที่ส่งมอบซ้ำหลังจากการ reorg ถือเป็นการส่งมอบที่คิดค่าบริการใหม่ ค่าบริการที่อยู่จะใช้จำนวนที่อยู่สูงสุดของการสมัครรับข้อมูลแต่ละรายการขณะออนไลน์ระหว่างวันตามเวลา UTC; โควตาที่อยู่ฟรีของบัญชีจะถูกแชร์ร่วมกันในทุกการสมัครรับข้อมูล โดยการสมัครรับข้อมูลที่เก่ากว่าจะได้รับสิทธิ์ก่อน ที่อยู่หนึ่งที่อยู่ในสองการสมัครรับข้อมูลจะถูกนับสองครั้ง; การเพิ่มเชนจะเปลี่ยนค่าธรรมเนียมอีเวนต์ ไม่ใช่ค่าธรรมเนียมที่อยู่
ดู คู่มือ Blockchain Webhook API สำหรับการตั้งค่า, การตรวจสอบลายเซ็น และ การกู้คืนการส่งมอบ คู่มือการชำระเงินด้วยสเตเบิลคอยน์ ครอบคลุมการตรวจสอบใบเสร็จและการโพลข้อมูลย้อนหลัง; การสมัครรับข้อมูล WebSocket ใช้การวัดปริมาณการเชื่อมต่อและการแจ้งเตือนของตนเอง ข้อผิดพลาดของคำขอแสดงอยู่ใน ข้อมูลอ้างอิงข้อผิดพลาด น้ำหนักด้านล่างนำมาจาก GET /v1/plans
| การใช้งาน | หน่วยการเรียกเก็บเงิน | CU |
|---|---|---|
push.address_day | ที่อยู่-วันที่คิดค่าบริการ | 33 |
push.history | คำขอประวัติที่สำเร็จ | 25 |
push.log | เหตุการณ์ข้อมูลที่ส่งมอบแล้ว | 150 |
push.native_transfer | เหตุการณ์ข้อมูลที่ส่งมอบแล้ว | 150 |
push.token_transfer | เหตุการณ์ข้อมูลที่ส่งมอบแล้ว | 150 |
ที่อยู่ฟรีต่อบัญชีต่อวัน UTC: 1000
โควตาที่อยู่ฟรีต่อบัญชีต่อวัน UTC ซึ่งแชร์ร่วมกันในทุกกลุ่มการสมัครรับข้อมูลโดยไม่คำนึงถึงแพ็กเกจ สำหรับแต่ละกลุ่ม จะนับจำนวนที่อยู่สูงสุดในขณะออนไลน์ระหว่างวันนั้น โดยจัดสรรโควตาตามลำดับ ID กลุ่มจากน้อยไปมาก หากที่อยู่เดียวกันอยู่ในสองกลุ่มจะนับสองครั้ง จำนวนเชนในกลุ่มจะไม่ทวีคูณจำนวนที่อยู่ กลุ่มที่ออฟไลน์หรือถูกลบตลอดทั้งวันจะไม่ถูกนำมาคำนวณ สำหรับแต่ละกลุ่ม จำนวนที่เหลือหลังจากหักส่วนแบ่งโควตาแล้ว จะถูกคูณด้วยน้ำหนัก CU ของ `push.address_day` ใน `method_weights` โควตาที่กำหนดค่าไว้ในปัจจุบันมาจากนโยบายราคาเดียวกันกับที่ใช้สำหรับค่าบริการที่อยู่-วัน ซึ่งไม่ใช่ขีดจำกัดความจุของบัญชีหรือโควตาแยกต่างหากต่อกลุ่ม
ตัวอย่าง: เหตุการณ์ native.transfer ที่ส่งมอบแล้ว 10 เหตุการณ์, คำขอประวัติที่สำเร็จ 2 คำขอ และที่อยู่-วันที่คิดค่าบริการ 10 ที่อยู่-วัน มีค่าใช้จ่าย 10 × 150 + 2 × 25 + 10 × 33 = 1880 CU ที่อยู่-วันที่คิดค่าบริการจะถูกนับหลังจากหักโควตาที่อยู่ฟรีของบัญชีแล้ว
ขั้นตอนถัดไป
- เลือกดูไดเรกทอรีชุดข้อมูล เพื่อดูชุดข้อมูลทั้งหมดที่ BlockVectra จัดทำดัชนี
- ดูแพ็กเกจฟรีและการกำหนดราคา เพื่อตรวจสอบสิทธิประโยชน์ในบัญชีของคุณ
- เข้าสู่ระบบคอนโซล เพื่อสร้าง API key
อัปเดตล่าสุด:
Webhook push
สร้างการติดตามหนึ่งรายการด้วย HTTPS URL ของคุณ เชน และแอดเดรสสูงสุด 1,000,000 รายการ; รายการที่ตรงกันของสินทรัพย์เนทีฟ โทเคน และ log จะถูก POST พร้อมเนื้อหาที่ลงนามอย่างน้อยหนึ่งครั้ง ตรวจสอบลายเซ็น ขจัด event ID ที่ซ้ำกัน และ replay รายการที่ตรงกันซึ่งเก็บรักษาไว้
การเติมเงินแบบเป็นโปรแกรมของ Agent
เติมเงินบัญชี RPC และ Data API บนเชนผ่าน HTTP โดยนักพัฒนาและ AI Agent ใช้ API key เพื่อตรวจสอบโทเค็นที่รองรับ รับที่อยู่สำหรับฝากเฉพาะของบัญชี และโพลตรวจสอบสถานะเครดิต