สิ่งที่ไม่คิดค่าบริการ: รหัสข้อผิดพลาดและกฎการเรียกเก็บเงิน

BlockVectra วัดปริมาณคำขอในหน่วย Compute Units (CU) โดยการเรียก JSON-RPC และ Data API จะถูกคิดค่าบริการหลังจากได้รับคำตอบกลับแล้วเท่านั้น คู่มือนี้สรุปกฎการพิจารณาการเรียกเก็บเงินตามรหัสสถานะ HTTP, การเรียก JSON-RPC และ Data API พร้อมการดำเนินการที่แนะนำสำหรับนักพัฒนา

รหัสสถานะ HTTP และกฎการเรียกเก็บเงิน

กฎการพิจารณาการเรียกเก็บเงินและการจัดการสำหรับการตอบกลับในระดับ HTTP มีดังนี้:

หมายเหตุ: เมื่อเข้าถึงผ่าน 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

กฎการเรียกเก็บเงินของ Data API

Data API ห่อหุ้มข้อมูลเชนแบบอ่านอย่างเดียวไว้ใน REST endpoint โดยการคิดค่าบริการและการจัดการข้อผิดพลาดจะเป็นไปตามกฎเหล่านี้:

รายละเอียดกฎ

• คิดค่าบริการเฉพาะการตอบกลับที่สำเร็จระดับ 2xx เท่านั้น
• การดำเนินการที่ไม่พร้อมใช้งานซึ่งอยู่นอกเหนือความครอบคลุม (เช่น เชนที่ไม่รองรับ หรือบล็อกที่อยู่นอกความครอบคลุมของ trace) จะส่งคืน HTTP 422 no_coverage ซึ่งไม่คิดค่าบริการแต่นับรวมในขีดจำกัดอัตรา
• การตอบกลับ HTTP 401, 402, 404 และ 429 ไม่คิดค่าบริการ สำหรับส่วนหัวการตอบกลับ (x-bv-meter: 1) โปรดดู รหัสสถานะ HTTP และกฎการเรียกเก็บเงิน

ตารางรหัสสถานะ Data API

ตรวจสอบยอดคงเหลือ (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) หากไม่มีส่วนหัวจะส่งคืน 401 missing_api_key; คีย์ที่ไม่ถูกต้องหรือถูกเพิกถอนจะส่งคืน 401 invalid_api_key (คีย์ที่หมดอายุจะส่งคืน 403 key_expired; บริการที่ไม่พร้อมใช้งานชั่วคราวจะส่งคืน 503 auth_unavailable หรือ billing_unavailable พร้อม Retry-After)
• การจำกัดอัตรา: มีขีดจำกัดอิสระที่ 5 คำขอต่อวินาทีต่อ key ID โดยไม่ขึ้นกับการวัดปริมาณและการเรียกเก็บเงินของ CU การส่งคำขอเกินขีดจำกัดจะส่งคืน HTTP 429 rate_limited พร้อมส่วนหัว Retry-After

ฟิลด์การตอบกลับ:

• key_id: สตริงตัวระบุของ API key
• plan: ประเภทแพ็กเกจของบัญชี (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 ในหน่วย CU
  • cu_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 ที่สูงขึ้น ให้เติมเงินบนเชนในคอนโซลตามขั้นตอนเหล่านี้:

1. เข้าสู่ระบบคอนโซล: ลงชื่อเข้าใช้ BlockVectra Console
2. ไปที่หน้า Billing: นำทางไปยัง หน้า Billing
3. รับที่อยู่เฉพาะของคุณ: ในการ์ดการเติมเงินบนเชน ให้คัดลอกที่อยู่การเติมเงินเฉพาะของบัญชีคุณหรือสแกนคิวอาร์โค้ด
4. โอนเงิน: โอนเงินโดยใช้เครือข่ายและ USDC / USDT / USDG ที่รองรับตามที่ระบุไว้ในหน้าดังกล่าวเท่านั้น เครือข่ายที่รองรับและจำนวนเงินเติมขั้นต่ำจะแสดงอยู่ในคอนโซล
5. บันทึกเครดิตอัตโนมัติ: เมื่อตรวจพบบนเชนแล้ว ธุรกรรมจะแสดงสถานะเป็น "Processing"; และเมื่อบันทึกเครดิตแล้ว เครดิตจะถูกเพิ่มเข้าสู่ยอดคงเหลือของคุณโดยอัตโนมัติ

ข้อควรระวังสำคัญ:

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

โปรแกรม Agent หรือเซิร์ฟเวอร์สามารถเรียก endpoint การเติมเงินได้โดยตรงโดยใช้ API key; ดูที่ คู่มือการเติมเงินแบบเป็นโปรแกรมของ Agent

การคิดค่าบริการ Webhook Push

บริการ Push มีน้ำหนักแยกต่างหากสำหรับอีเวนต์ข้อมูลที่ส่งมอบสำเร็จ, การสืบค้นประวัติที่สำเร็จ และ address-days ที่คิดค่าบริการได้ การเรียกการจัดการนอกเหนือจากประวัติอีเวนต์, ความพยายามส่งมอบที่ล้มเหลว, การลองใหม่อัตโนมัติ และอีเวนต์ควบคุมจะไม่มีค่าบริการ อีเวนต์ที่ส่งมอบแต่ละรายการจะถูกคิดค่าบริการครั้งเดียว; การเล่นซ้ำของลูกค้าและอีเวนต์ตามสายหลัก (canonical events) ที่ส่งมอบซ้ำหลังจากการ reorg ถือเป็นการส่งมอบที่คิดค่าบริการใหม่ ค่าบริการที่อยู่จะใช้จำนวนที่อยู่สูงสุดของการสมัครรับข้อมูลแต่ละรายการขณะออนไลน์ระหว่างวันตามเวลา UTC; โควตาที่อยู่ฟรีของบัญชีจะถูกแชร์ร่วมกันในทุกการสมัครรับข้อมูล โดยการสมัครรับข้อมูลที่เก่ากว่าจะได้รับสิทธิ์ก่อน ที่อยู่หนึ่งที่อยู่ในสองการสมัครรับข้อมูลจะถูกนับสองครั้ง; การเพิ่มเชนจะเปลี่ยนค่าธรรมเนียมอีเวนต์ ไม่ใช่ค่าธรรมเนียมที่อยู่

ดู คู่มือ Blockchain Webhook API สำหรับการตั้งค่า, การตรวจสอบลายเซ็น และ การกู้คืนการส่งมอบ คู่มือการชำระเงินด้วยสเตเบิลคอยน์ ครอบคลุมการตรวจสอบใบเสร็จและการโพลข้อมูลย้อนหลัง; การสมัครรับข้อมูล WebSocket ใช้การวัดปริมาณการเชื่อมต่อและการแจ้งเตือนของตนเอง ข้อผิดพลาดของคำขอแสดงอยู่ใน ข้อมูลอ้างอิงข้อผิดพลาด น้ำหนักด้านล่างนำมาจาก GET /v1/plans

ขั้นตอนถัดไป

• เลือกดูไดเรกทอรีชุดข้อมูล เพื่อดูชุดข้อมูลทั้งหมดที่ BlockVectra จัดทำดัชนี
• ดูแพ็กเกจฟรีและการกำหนดราคา เพื่อตรวจสอบสิทธิประโยชน์ในบัญชีของคุณ
• เข้าสู่ระบบคอนโซล เพื่อสร้าง API key