Qué no se factura: códigos de error y reglas de facturación

BlockVectra mide las solicitudes en unidades de cómputo (CU). Las llamadas JSON-RPC y Data API se facturan solo después de obtener una respuesta. Esta guía resume las reglas que determinan la facturación según los códigos de estado HTTP, las llamadas JSON-RPC y la Data API, junto con las acciones recomendadas para desarrolladores.

Códigos de estado HTTP y reglas de facturación

Las reglas que determinan la facturación y el tratamiento de las respuestas HTTP son las siguientes:

Nota: Al acceder a través de Cloudflare, este puede devolver páginas de error 52x o 1015; no las genera el servicio.

Encabezados de respuesta de cargos y saldo: Al enviar x-bv-meter: 1 en solicitudes HTTP (tanto JSON-RPC como Data API), una respuesta que haya facturado al menos una llamada devuelve x-bv-cu-charged (las unidades de cómputo facturadas por esta solicitud, o la suma de las llamadas facturadas de un lote) y x-bv-balance-units (las unidades de saldo restantes de la cuenta inmediatamente después de este cargo, negativas si hay sobregiro; se omite si se desconoce el saldo). Las solicitudes sin x-bv-meter: 1, las respuestas sin llamadas facturadas y las respuestas de error 402, 403, 429 o 503 omiten ambos encabezados. Los scripts del navegador pueden acceder a estos encabezados de respuesta mediante CORS, mientras que WebSocket no los utiliza. El saldo resta el uso total pendiente de liquidación redondeado hacia arriba una sola vez a unidades enteras; la liquidación por hora redondea hacia abajo, por lo que el saldo comunicado puede aumentar hasta una unidad después de la liquidación.

Códigos de error JSON-RPC y reglas de facturación

El mismo código de error puede proceder de la plataforma o del nodo, y la facturación es distinta:

• Errores generados por la propia plataforma: nunca se facturan;
• Errores devueltos por el nodo: se transmiten sin cambios y se facturan según el peso del método, con las únicas excepciones de códigos de error del nodo que se enumeran a continuación.

Detalles de las reglas

• Errores del nodo no facturados: Los errores del nodo -32002 (tiempo de espera del lote agotado), -32003 (respuesta del lote demasiado grande) y -32600 (lote rechazado en su totalidad) indican que el nodo abandonó la llamada de forma anticipada; estos errores y las notificaciones del mismo lote no se facturan. Los errores del nodo -32601 (método expuesto no implementado) y -32603 (fallo interno del nodo) no se facturan por HTTP ni WebSocket y no afectan a otras llamadas o notificaciones del lote. Además, 4444 (bloque podado) y -32000 (estado histórico fuera de la ventana de historial de estado del nodo, definida por state_window_blocks en GET /v1/chains) no se facturan ni afectan a otras llamadas del lote.
• Errores del nodo facturados: Otros errores devueltos por el nodo se facturan según el peso del método cuando informan del resultado de la cadena, como execution reverted (-32000 o 3 con data) o el propio -32602 invalid argument del nodo.
• Admisión por saldo y sincronización: -32020 indica que el saldo de la cuenta es insuficiente y requiere una recarga; cuando se conoce el saldo, error.data.balance_units y error.data.balance_cu contienen el saldo restante (puede ser negativo). Una clave recién creada puede devolver -32021 (503) durante unos segundos; espere Retry-After y vuelva a intentarlo.
• Fallos del servicio upstream: Un -32603 generado por la plataforma debido a un fallo de comunicación con el servicio upstream o a una respuesta mal formada (upstream unavailable, no response from upstream, malformed upstream response) incluye data.reason: upstream_unavailable.
• Facturación de notificaciones: Las notificaciones (204) se facturan según el peso de sus métodos.

Tabla de códigos de error JSON-RPC

Reglas de facturación de la Data API

La Data API ofrece datos de cadenas de solo lectura mediante endpoints REST. Su facturación y tratamiento de errores siguen estas reglas:

Detalles de las reglas

• Solo se facturan las respuestas correctas 2xx.
• Las operaciones no disponibles fuera de la cobertura (como cadenas no admitidas o bloques fuera de la cobertura de trazas) devuelven HTTP 422 no_coverage, que no se factura pero cuenta para los límites de frecuencia.
• Las respuestas HTTP 401, 402, 404 y 429 no se facturan. Para conocer los encabezados de respuesta (x-bv-meter: 1), consulte Códigos de estado HTTP y reglas de facturación.

Tabla de códigos de estado de la Data API

Consultar saldo (GET /v1/account)

El titular de una API key puede consultar directamente el saldo y los detalles de la cuota de la clave sin facturación ni descuento de unidades de cómputo (CU):

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

• Gratuito y no facturado: GET /v1/account es gratuito. Nunca se factura ni descuenta CU, y devuelve HTTP 200 con el saldo actual incluso si es cero o negativo (nunca devuelve 402).
• Autenticación: La autenticación de la clave usa exclusivamente el encabezado x-api-key (no se aceptan claves en la ruta ni tokens Bearer). La ausencia del encabezado devuelve 401 missing_api_key; las claves no válidas o revocadas devuelven 401 invalid_api_key. (Las claves caducadas devuelven 403 key_expired; la indisponibilidad transitoria del servicio devuelve 503 auth_unavailable o billing_unavailable con Retry-After.)
• Límite de frecuencia: Tiene un límite independiente de 5 solicitudes por segundo por ID de clave, independiente de la medición y facturación de CU. Superarlo devuelve HTTP 429 rate_limited con un encabezado Retry-After.

Campos de respuesta:

• key_id: Cadena de texto que identifica la API key.
• plan: Tipo de plan de la cuenta (free cuando la cuenta tiene una cuota de llamadas del plan gratuito; paid en caso contrario).
• balance_units: Saldo restante de la cuenta en unidades (puede ser cero o negativo).
• balance_cu: Saldo restante convertido a unidades de cómputo (CU).
• balance_as_of_age_ms: Milisegundos transcurridos desde que se leyó el saldo de su fuente de datos.
• key: Límites específicos de la clave y detalles de su cuota:
  • cu_per_sec: Frecuencia de reposición del token bucket en CU por segundo.
  • burst_cu: Capacidad de ráfaga del token bucket en CU.
  • cu_cap: Límite de CU durante toda la vida útil de esta clave, o null si no tiene límite.
  • cu_cap_remaining: CU restantes dentro de cu_cap, o null si no tiene límite (puede ser cero o negativo).
  • expires_at: Marca de tiempo de caducidad RFC 3339, o null si la clave nunca caduca.

Ejemplo de respuesta:

{
  "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>"
  }
}

Precios y paso a un plan de pago

El coste específico de todas las llamadas facturadas se determina mediante los pesos CU publicados:

• Para consultar los pesos de todos los métodos y operaciones, consulte la tabla de pesos de métodos y las reglas de medición en CU de JSON-RPC.
• Para conocer los precios de los planes y los detalles de liquidación, consulte la página de Precios.
• Paso a un plan de pago: una recarga de pago elimina el límite de llamadas por segundo del plan gratuito; cada clave sigue sujeta a los límites de frecuencia y ráfaga de CU.

Proceso de recarga on-chain

Cuando el saldo de su cuenta sea insuficiente o necesite mayor capacidad de procesamiento, recargue on-chain en la consola siguiendo estos pasos:

1. Inicie sesión en la consola: Acceda a la Consola de BlockVectra.
2. Vaya a la página de Facturación: Abra la página de Facturación.
3. Obtenga su dirección dedicada: En la tarjeta de recarga on-chain, copie la dirección de recarga dedicada de su cuenta o escanee el código QR.
4. Transfiera fondos: Transfiera únicamente mediante las redes admitidas y las USDC / USDT / USDG indicadas en la página. Las redes admitidas y los montos mínimos de recarga se muestran en la consola.
5. Acreditación automática: Una vez detectadas on-chain, las transacciones aparecen como "En proceso"; una vez acreditadas, los créditos se añaden automáticamente a su saldo.

Notas importantes:

• Use únicamente las redes y los tokens indicados explícitamente en la consola. Las transferencias en cadenas no admitidas o con tokens incorrectos no pueden acreditarse automáticamente.
• Asegúrese de que cada transferencia alcance el monto mínimo de recarga indicado en la consola.
• Una vez acreditada su primera recarga de pago, su cuenta pasa a ser de pago y se elimina el límite de llamadas por segundo del plan gratuito.

Los agentes o programas de servidor pueden llamar directamente a los endpoints de recarga mediante una API key; consulte la guía de recarga programática para agentes.

Facturación de notificaciones Webhook

Las notificaciones tienen pesos distintos para los eventos de datos entregados, las consultas de historial correctas y los días de dirección facturables. Las llamadas de gestión distintas del historial de eventos, los intentos de entrega fallidos, los reintentos automáticos y los eventos de control son gratuitos. Cada evento entregado se cobra una vez; la reproducción solicitada por el cliente y los eventos canónicos entregados de nuevo tras una reorganización son nuevas entregas facturadas. Los cargos por dirección usan el número máximo de direcciones de cada suscripción mientras estuvo en línea durante el día UTC; la cuota gratuita de direcciones de la cuenta se comparte entre suscripciones y las más antiguas la usan primero. Una dirección en dos suscripciones se cuenta dos veces; añadir cadenas cambia las tarifas de eventos, no las de direcciones.

Consulte la guía de la API de Webhooks de blockchain para la configuración, la verificación de firmas y la recuperación de entregas. La guía de pagos con stablecoins cubre la validación de recibos y la carga histórica mediante sondeo; las suscripciones WebSocket usan su propia medición de conexiones y notificaciones. Los errores de solicitud se enumeran en la referencia de errores. Los pesos siguientes proceden de GET /v1/plans.

Próximos pasos

• Explore el catálogo de conjuntos de datos para ver todos los conjuntos de datos que indexa BlockVectra.
• Consulte el plan gratuito y los precios para comprobar qué incluye su cuenta.
• Inicie sesión en la consola para crear una API key.