과금되지 않는 요청: 오류 코드 및 과금 규칙

BlockVectra는 요청을 Compute Unit(CU) 단위로 측정합니다. JSON-RPC 및 Data API 호출은 응답을 수신한 후에만 과금됩니다. 이 가이드에서는 HTTP 상태 코드, JSON-RPC 호출 및 Data API 전반에 걸친 과금 결정 규칙과 개발자를 위한 권장 조치 사항을 정리합니다.

HTTP 상태 코드와 과금 규칙

HTTP 수준 응답에 대한 과금 판정 및 처리 규칙은 다음과 같습니다:

참고: Cloudflare를 통해 접속할 때 Cloudflare에서 52x 또는 1015 오류 페이지를 반환할 수 있으며, 이는 서비스에서 생성된 것이 아닙니다.

과금 및 잔액 응답 헤더: HTTP 요청에 x-bv-meter: 1을 전송할 때(JSON-RPC 및 Data API 모두 적용 가능), 하나 이상의 호출에 과금된 응답은 x-bv-cu-charged(해당 요청에 과금된 Compute Unit 수, 또는 배치의 과금된 호출들의 합계)와 x-bv-balance-units(해당 과금 직후 계정의 잔여 잔액 단위, 초과 인출 시 음수; 잔액을 알 수 없는 경우 생략)를 반환합니다. x-bv-meter: 1이 없는 요청, 과금된 항목이 없는 응답, 402, 403, 429 또는 503 오류 응답에서는 두 헤더가 모두 생략됩니다. 이 응답 헤더는 CORS를 통해 브라우저 스크립트에서 접근할 수 있으며 WebSocket에서는 사용되지 않습니다. 잔액은 아직 정산되지 않은 총 사용량을 전체 단위로 한 번 올림하여 차감하며, 시간별 정산 시 내림 처리되므로 정산 후 보고되는 잔액이 최대 1단위까지 증가할 수 있습니다.

JSON-RPC 오류 코드와 과금 규칙

동일한 오류 코드라도 플랫폼 자체에서 발생할 수도 있고 노드에서 반환될 수도 있으며, 과금 여부가 달라집니다:

• 플랫폼 자체에서 생성된 오류: 일체 과금되지 않음;
• 노드에서 반환된 오류: 그대로 전달되며 메서드 가중치에 따라 과금되나, 아래 나열된 노드 오류 코드만 예외로 처리됩니다.

규칙 세부 사항

• 과금되지 않는 노드 오류: 노드의 -32002(배치 타임아웃), -32003(배치 응답 너무 큼), -32600(배치 전체 거부)은 노드가 호출을 조기에 중단했음을 나타내며, 해당 호출 및 동일 배치 내의 모든 알림은 과금되지 않습니다. 노드의 -32601(노출된 메서드 미구현) 및 -32603(노드 내부 오류)은 HTTP 또는 WebSocket을 통해 과금되지 않으며 배치 내 다른 호출이나 알림에 영향을 주지 않습니다. 또한 4444(가지치기된 블록) 및 -32000(노드의 상태 기록 윈도우 외부의 과거 상태, GET /v1/chains의 state_window_blocks로 정의됨)은 과금되지 않으며 배치 내 다른 호출에 영향을 주지 않습니다.
• 과금되는 노드 오류: 체인의 실행 결과를 보고하는 경우 노드에서 반환된 기타 오류는 메서드 가중치에 따라 과금됩니다. 예를 들어 execution reverted(-32000 또는 data가 포함된 3), 노드 자체의 -32602 invalid argument 등이 있습니다.
• 잔액 승인 및 동기화: -32020은 계정 잔액 부족을 나타내며 충전이 필요합니다. 잔액을 알 수 있는 경우 error.data.balance_units 및 error.data.balance_cu에 잔여량이 전달됩니다(음수일 수 있음). 새로 생성된 키는 몇 초 동안 -32021(503)을 반환할 수 있으므로 Retry-After 동안 대기한 후 재시도하세요.
• 업스트림 오류: 업스트림 통신 실패 또는 잘못된 형식의 응답(upstream unavailable, no response from upstream, malformed upstream response)으로 인해 플랫폼에서 생성된 -32603은 data.reason: upstream_unavailable을 전달합니다.
• 알림 과금: 알림(204)은 해당 메서드 가중치에 따라 과금됩니다.

JSON-RPC 오류 코드 표

Data API 과금 규칙

Data API는 읽기 전용 체인 데이터를 REST 엔드포인트로 래핑합니다. 과금 및 오류 처리는 다음 규칙을 따릅니다:

규칙 세부 사항

• 2xx 성공 응답에만 과금됩니다.
• 지원 범위를 벗어난 사용 불가능한 작업(지원되지 않는 체인 또는 추적 범위를 벗어난 블록 등)은 HTTP 422 no_coverage를 반환하며, 과금되지 않으나 속도 제한에는 산입됩니다.
• HTTP 401, 402, 404 및 429 응답은 과금되지 않습니다. 응답 헤더(x-bv-meter: 1)에 대해서는 HTTP 상태 코드와 과금 규칙을 참조하세요.

Data API 상태 코드 표

잔액 조회 (GET /v1/account)

API key 소유자는 과금이 발생하거나 Compute Unit(CU)을 차감하지 않고도 잔액 및 키 한도 세부 정보를 직접 확인할 수 있습니다:

curl -H "x-api-key: $BLOCKVECTRA_API_KEY" https://api.blockvectra.com/v1/account

• 무료 및 미과금: GET /v1/account는 무료입니다. 일체 과금되지 않으며, CU를 차감하지 않고, 잔액이 0이거나 음수인 경우에도 HTTP 200과 함께 현재 잔액을 반환합니다(402를 절대 반환하지 않음).
• 인증: 키 인증에는 x-api-key 헤더만 독점적으로 사용됩니다(경로 키 및 Bearer 토큰은 허용되지 않음). 헤더가 누락되면 401 missing_api_key를 반환하고, 유효하지 않거나 해지된 키는 401 invalid_api_key를 반환합니다. (만료된 키는 403 key_expired를 반환하며, 일시적인 서비스 장애 시 Retry-After와 함께 503 auth_unavailable 또는 billing_unavailable을 반환합니다.)
• 속도 제한: CU 측정 및 과금과 무관하게 키 ID당 초당 5개 요청의 독립적인 제한이 적용됩니다. 한도를 초과하면 Retry-After 헤더와 함께 HTTP 429 rate_limited를 반환합니다.

응답 필드:

• key_id: API key의 식별자 문자열.
• plan: 계정 플랜 유형 (계정에 무료 플랜 호출 속도 할당량이 있는 경우 free, 그렇지 않으면 paid).
• balance_units: 단위 기준 계정 잔여 잔액 (0 또는 음수일 수 있음).
• balance_cu: Compute Unit(CU)으로 환산된 잔여 잔액.
• balance_as_of_age_ms: 데이터 소스에서 잔액을 읽어온 후 경과한 밀리초.
• key: 키별 제한 및 할당량 세부 정보:
  • cu_per_sec: 초당 CU 기준 토큰 버킷 리필 속도.
  • burst_cu: CU 기준 토큰 버킷 버스트 용량.
  • cu_cap: 해당 키의 총 수명 CU 한도, 한도가 없는 경우 null.
  • cu_cap_remaining: cu_cap 아래 남은 CU, 한도가 없는 경우 null (0 또는 음수일 수 있음).
  • 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 가중치에 의해 결정됩니다:

• 모든 메서드와 작업의 가중치를 확인하려면 메서드 가중치 표 및 JSON-RPC CU 측정 규칙을 참조하세요.
• 플랜 요금 및 정산 세부 정보는 요금 페이지를 참조하세요.
• 유료 플랜으로 업그레이드: 유료 충전을 진행하면 무료 플랜의 초당 호출 수 제한이 해제되며, 각 키는 여전히 CU 속도 및 버스트 제한의 적용을 받습니다.

온체인 충전 프로세스

계정 잔액이 부족하거나 더 높은 처리량이 필요한 경우, 다음 단계에 따라 콘솔에서 온체인 충전을 진행하세요:

1. 콘솔 로그인: BlockVectra 콘솔에 로그인합니다.
2. 결제 관리 페이지로 이동: 결제 관리 페이지로 이동합니다.
3. 전용 주소 확인: 온체인 충전 카드에서 계정의 전용 충전 주소를 복사하거나 QR 코드를 스캔합니다.
4. 자금 전송: 페이지에 나열된 지원 네트워크 및 USDC / USDT / USDG만 사용하여 전송하세요. 지원되는 네트워크 및 최소 충전 금액은 콘솔에 표시됩니다.
5. 자동 크레딧 반영: 온체인에서 감지되면 트랜잭션이 "처리 중"으로 표시되며, 완료되면 크레딧이 잔액에 자동으로 추가됩니다.

주의 사항:

• 콘솔에 명시적으로 나열된 네트워크와 토큰만 사용하세요. 지원되지 않는 체인이나 잘못된 토큰으로 전송된 금액은 자동으로 반영될 수 없습니다.
• 각 전송 금액이 콘솔에 안내된 최소 충전 금액 이상인지 확인하세요.
• 첫 유료 충전이 반영되면 계정이 유료 계정으로 업그레이드되어 무료 플랜의 초당 호출 수 제한이 해제됩니다.

에이전트나 서버 프로그램은 API key를 사용하여 충전 엔드포인트를 직접 호출할 수 있습니다. 에이전트 프로그래밍 방식 충전 가이드를 참조하세요.

Webhook 푸시 과금

푸시는 전달된 데이터 이벤트, 성공한 이력 조회 및 과금 대상 주소-일에 대해 각각 별도의 가중치가 적용됩니다. 이벤트 이력 조회를 제외한 관리 호출, 실패한 전달 시도, 자동 재시도 및 제어 이벤트는 무료입니다. 전달된 각 이벤트는 1회 과금되며, 고객 리플레이 및 블록 재구성(reorg) 후 다시 전달된 표준 체인 이벤트는 새로운 과금 대상 전달로 처리됩니다. 주소 요금은 각 구독이 UTC 일자 중 온라인 상태였던 기간 동안의 최대 주소 수를 기준으로 부과됩니다. 계정 무료 주소 할당량은 구독 간에 공유되며, 먼저 생성된 구독이 우선적으로 이를 사용합니다. 두 개의 구독에 동일한 주소가 포함되면 2회 계산되며, 체인을 추가하면 이벤트 요금은 변경되지만 주소 요금은 증가하지 않습니다.

설정, 서명 검증 및 전달 복구는 블록체인 Webhook API 가이드를 참조하세요. 스테이블코인 결제 가이드에서는 수신 확인 및 폴링 백필을 다루며, WebSocket 구독은 자체적인 연결 및 알림 측정 방식을 사용합니다. 요청 오류는 오류 레퍼런스에 나열되어 있습니다. 아래 가중치는 GET /v1/plans에서 가져옵니다.

다음 단계

• 데이터셋 디렉터리 둘러보기: BlockVectra가 인덱싱하는 모든 데이터셋 확인.
• 무료 플랜 및 요금 확인: 내 계정에 포함된 혜택 확인.
• 콘솔 로그인: API key 생성.