Ce qui n'est pas facturé : codes d'erreur et règles de facturation

BlockVectra mesure les requêtes en Compute Units (CU). Les appels JSON-RPC et Data API ne sont facturés qu'après l'obtention d'une réponse. Ce guide résume les règles de détermination de la facturation pour les codes d'état HTTP, les appels JSON-RPC et la Data API, ainsi que les actions recommandées pour les développeurs.

Codes d'état HTTP et règles de facturation

Les règles de détermination de la facturation et de traitement pour les réponses au niveau HTTP sont les suivantes :

Remarque : lors d'un accès via Cloudflare, Cloudflare peut renvoyer des pages d'erreur 52x ou 1015 ; celles-ci ne sont pas générées par le service.

En-têtes de réponse pour la facturation et le solde : lors de l'envoi de x-bv-meter: 1 sur les requêtes HTTP (applicable à la fois au JSON-RPC et à la Data API), une réponse qui a facturé au moins un appel renvoie x-bv-cu-charged (les Compute Units facturées pour cette requête, ou la somme des appels facturés d'un batch) et x-bv-balance-units (les unités de solde restantes du compte immédiatement après cette imputation, négatives en cas de découvert ; omises si le solde est inconnu). Les requêtes sans x-bv-meter: 1, les réponses où rien n'a été facturé, ainsi que les réponses d'erreur 402, 403, 429 ou 503 omettent ces deux en-têtes. Ces en-têtes de réponse sont accessibles aux scripts de navigateur via CORS, tandis que WebSocket ne les utilise pas. Le solde soustrait l'utilisation totale non réglée arrondie au supérieur une fois aux unités entières ; le règlement horaire arrondit à l'inférieur, de sorte que le solde indiqué peut augmenter jusqu'à une unité après le règlement.

Codes d'erreur JSON-RPC et règles de facturation

Le même code d'erreur peut provenir de la plateforme ou du nœud, et la facturation diffère :

• Erreurs générées par la plateforme elle-même : jamais facturées ;
• Erreurs renvoyées par le nœud : transmises telles quelles et facturées au poids de la méthode, avec pour seules exceptions les codes d'erreur de nœud énumérés ci-dessous.

Détails des règles

• Erreurs de nœud non facturées : les codes du nœud -32002 (expiration du délai de batch), -32003 (réponse de batch trop volumineuse) et -32600 (batch rejeté dans son ensemble) indiquent que le nœud a abandonné l'appel prématurément ; ces appels ainsi que toutes les notifications du même batch ne sont pas facturés. Les erreurs de nœud -32601 (méthode exposée non implémentée) et -32603 (défaillance interne du nœud) ne sont pas facturées sur HTTP ou WebSocket et n'affectent pas les autres appels ou notifications du batch. De plus, 4444 (bloc élagué) et -32000 (état historique en dehors de la fenêtre d'historique d'état du nœud, définie par state_window_blocks dans GET /v1/chains) ne sont pas facturés et n'affectent pas les autres appels du batch.
• Erreurs de nœud facturées : les autres erreurs renvoyées par le nœud sont facturées au poids de la méthode lorsqu'elles rapportent le résultat de la chaîne, telles que execution reverted (-32000 ou 3 avec data), le -32602 invalid argument propre au nœud.
• Admission de solde et synchronisation : -32020 indique un solde de compte insuffisant et nécessite une recharge ; lorsque le solde est connu, error.data.balance_units et error.data.balance_cu indiquent ce qu'il reste (cela peut être négatif). Une clé nouvellement créée peut renvoyer -32021 (503) pendant quelques secondes ; attendez Retry-After et réessayez.
• Échecs en amont : un code -32603 généré par la plateforme en raison d'une défaillance de communication en amont ou d'une réponse malformée (upstream unavailable, no response from upstream, malformed upstream response) contient data.reason: upstream_unavailable.
• Facturation des notifications : les notifications (204) sont facturées au poids de leur méthode.

Tableau des codes d'erreur JSON-RPC

Règles de facturation de la Data API

La Data API encapsule les données de chaîne en lecture seule dans des points de terminaison REST. Sa facturation et sa gestion des erreurs suivent ces règles :

Détails des règles

• Seules les réponses 2xx réussies sont facturées.
• Les opérations indisponibles en dehors de la couverture (telles que les chaînes non prises en charge ou les blocs hors de la couverture des traces) renvoient HTTP 422 no_coverage, qui n'est pas facturé mais compte dans les limites de débit.
• Les réponses HTTP 401, 402, 404 et 429 ne sont pas facturées. Pour les en-têtes de réponse (x-bv-meter: 1), voir les Codes d'état HTTP et règles de facturation.

Tableau des codes d'état de la Data API

Consulter le solde (GET /v1/account)

Le détenteur d'une clé API peut vérifier le solde et les détails des quotas de la clé directement sans encourir de facturation ni déduire de Compute Units (CU) :

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

• Gratuit et non facturé : GET /v1/account est gratuit. Il n'est jamais facturé, ne déduit pas de CU, et renvoie HTTP 200 avec le solde actuel même lorsqu'il est nul ou négatif (il ne renvoie jamais 402).
• Authentification : l'authentification par clé utilise exclusivement l'en-tête x-api-key (les clés dans le chemin et les jetons Bearer ne sont pas acceptés). L'absence d'en-tête renvoie 401 missing_api_key ; les clés invalides ou révoquées renvoient 401 invalid_api_key. (Les clés expirées renvoient 403 key_expired ; les indisponibilités temporaires de service renvoient 503 auth_unavailable ou billing_unavailable avec Retry-After.)
• Limitation de débit : dispose d'une limite indépendante de 5 requêtes par seconde par ID de clé, indépendamment du comptage des CU et de la facturation. Le dépassement de la limite renvoie HTTP 429 rate_limited avec un en-tête Retry-After.

Champs de réponse :

• key_id : la chaîne d'identification de la clé API.
• plan : le type de forfait du compte (free lorsque le compte dispose d'un quota de débit d'appels de forfait gratuit ; paid dans le cas contraire).
• balance_units : le solde restant du compte en unités (peut être nul ou négatif).
• balance_cu : le solde restant converti en Compute Units (CU).
• balance_as_of_age_ms : millisecondes écoulées depuis la lecture du solde à partir de sa source de données.
• key : limites spécifiques à la clé et détails des quotas :
  • cu_per_sec : taux de recharge du token bucket en CU par seconde.
  • burst_cu : capacité de burst du token bucket en CU.
  • cu_cap : plafond total de CU pour cette clé sur sa durée de vie, ou null si non plafonné.
  • cu_cap_remaining : CU restantes sous cu_cap, ou null si non plafonné (peut être nul ou négatif).
  • expires_at : horodatage d'expiration RFC 3339, ou null si la clé n'expire jamais.

Exemple de réponse :

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

Tarifs et passages au forfait supérieur

Le coût spécifique de tous les appels facturés est déterminé par les pondérations en CU publiées :

• Pour consulter les pondérations de toutes les méthodes et opérations, voir le tableau des pondérations des méthodes et les Règles de mesure des CU JSON-RPC.
• Pour les tarifs des forfaits et les détails de règlement, voir la page Tarifs.
• Passage à un forfait payant : effectuer une recharge payante supprime la limite d'appels par seconde du forfait gratuit ; chaque clé reste soumise aux limites de débit et de burst en CU.

Processus de recharge on-chain

Lorsque le solde de votre compte est insuffisant ou que vous avez besoin d'un débit plus élevé, rechargez on-chain dans la console en suivant ces étapes :

1. Se connecter à la console : connectez-vous à la console BlockVectra.
2. Accéder à la page Facturation : accédez à la page Facturation.
3. Obtenir votre adresse dédiée : dans la carte de recharge on-chain, copiez l'adresse de recharge dédiée de votre compte ou scannez le code QR.
4. Transférer des fonds : transférez uniquement à l'aide des réseaux et USDC / USDT / USDG pris en charge répertoriés sur la page. Les réseaux pris en charge et les montants minimaux de recharge sont affichés dans la console.
5. Crédit automatique : une fois détectées on-chain, les transactions s'affichent comme « En cours de traitement » ; une fois créditées, les crédits sont automatiquement ajoutés à votre solde.

Remarques importantes :

• Utilisez uniquement les réseaux et tokens explicitement répertoriés dans la console. Les transferts sur des chaînes non prises en charge ou avec des tokens incorrects ne peuvent pas être crédités automatiquement.
• Assurez-vous que chaque transfert respecte le montant minimal de recharge indiqué dans la console.
• Dès que votre première recharge payante est créditée, votre compte passe à un compte payant, supprimant la limite d'appels par seconde du forfait gratuit.

Les programmes d'agents ou de serveurs peuvent appeler directement les points de terminaison de recharge à l'aide d'une clé API ; voir le guide de recharge programmatique d'agent.

Facturation push des Webhooks

Le push dispose de pondérations distinctes pour les événements de données livrés, les requêtes d'historique réussies et les jours-adresses facturables. Les appels de gestion autres que l'historique des événements, les tentatives de distribution échouées, les nouvelles tentatives automatiques et les événements de contrôle sont gratuits. Chaque événement livré est facturé une seule fois ; le rejeu par le client et les événements canoniques relivrés après une réorganisation constituent de nouvelles livraisons facturées. Les frais d'adresse utilisent le nombre maximal d'adresses de chaque abonnement pendant qu'il est en ligne au cours de la journée UTC ; l'allocation d'adresses gratuites du compte est partagée entre les abonnements, les abonnements les plus anciens l'utilisant en premier. Une adresse figurant dans deux abonnements est comptée deux fois ; l'ajout de chaînes modifie les frais d'événements, pas les frais d'adresse.

Consultez le guide de la Webhook API blockchain pour la configuration, la vérification de signature et la reprise de distribution. Le guide des paiements en stablecoins couvre la validation des reçus et le rattrapage par interrogation ; les abonnements WebSocket utilisent leur propre mesure de connexion et de notification. Les erreurs de requête sont répertoriées dans la référence des erreurs. Les pondérations ci-dessous proviennent de GET /v1/plans.

Prochaines étapes

• Parcourir le répertoire des jeux de données pour voir chaque jeu de données indexé par BlockVectra.
• Consulter le forfait gratuit et les tarifs pour vérifier ce que comprend votre compte.
• Se connecter à la console pour créer une clé API.