O que não é cobrado: códigos de erro e regras de cobrança

A BlockVectra mede as requisições em Compute Units (CU). As chamadas JSON-RPC e Data API são cobradas apenas após a obtenção de uma resposta. Este guia resume as regras de determinação de cobrança em códigos de status HTTP, chamadas JSON-RPC e na Data API, além das ações recomendadas para desenvolvedores.

Códigos de status HTTP e regras de cobrança

As regras de determinação e tratamento de cobrança para respostas no nível HTTP são as seguintes:

Observação: ao acessar por meio da Cloudflare, a Cloudflare pode retornar páginas de erro 52x ou 1015; elas não são geradas pelo serviço.

Cabeçalhos de resposta de cobrança e saldo: ao enviar x-bv-meter: 1 em requisições HTTP (aplicável tanto a JSON-RPC quanto a Data API), uma resposta que cobrou ao menos uma chamada retorna x-bv-cu-charged (as Compute Units cobradas por esta requisição ou a soma entre as chamadas cobradas de um lote) e x-bv-balance-units (as unidades de saldo restantes da conta logo após essa cobrança, negativas em caso de cheque especial; omitidas se o saldo for desconhecido). Requisições sem x-bv-meter: 1, respostas em que nada foi cobrado e respostas de erro 402, 403, 429 ou 503 omitem ambos os cabeçalhos. Esses cabeçalhos de resposta são acessíveis a scripts do navegador via CORS, enquanto o WebSocket não os utiliza. O saldo subtrai o uso total não liquidado arredondado para cima uma vez para unidades inteiras; a liquidação horária arredonda para baixo, portanto o saldo informado pode aumentar em até uma unidade após a liquidação.

Códigos de erro JSON-RPC e regras de cobrança

O mesmo código de erro pode ser originado da plataforma ou do nó, e a cobrança difere:

• Erros gerados pela própria plataforma: nunca são cobrados;
• Erros retornados pelo nó: são repassados no estado original e cobrados pelo peso do método, com apenas os códigos de erro do nó listados abaixo como exceções.

Detalhes das regras

• Erros do nó não cobrados: os erros do nó -32002 (tempo limite do lote), -32003 (resposta do lote muito grande) e -32600 (lote rejeitado por completo) indicam que o nó abandonou a chamada precocemente; esses erros e quaisquer notificações no mesmo lote não são cobrados. O -32601 do nó (método exposto não implementado) e o -32603 (falha interna do nó) não são cobrados via HTTP ou WebSocket e não afetam outras chamadas ou notificações no lote. Além disso, 4444 (bloco podado) e -32000 (estado histórico fora da janela de histórico de estado do nó, definida por state_window_blocks em GET /v1/chains) não são cobrados e não afetam outras chamadas no lote.
• Erros do nó cobrados: outros erros retornados pelo nó são cobrados pelo peso do método quando relatam o resultado da rede, como execution reverted (-32000 ou 3 com data), ou o próprio -32602 invalid argument do nó.
• Admissão de saldo e sincronização: -32020 indica saldo de conta insuficiente e requer recarga; quando o saldo é conhecido, error.data.balance_units e error.data.balance_cu informam o que resta (podendo ser negativo). Uma chave recém-criada pode retornar -32021 (503) por alguns segundos; aguarde o Retry-After e tente novamente.
• Falhas de upstream: um -32603 gerado pela plataforma devido a falha de comunicação com upstream ou resposta malformada (upstream unavailable, no response from upstream, malformed upstream response) traz data.reason: upstream_unavailable.
• Cobrança de notificações: notificações (204) são cobradas pelos pesos dos seus métodos.

Tabela de códigos de erro JSON-RPC

Regras de cobrança da Data API

A Data API encapsula dados de rede somente leitura em endpoints REST. Sua cobrança e tratamento de erros seguem estas regras:

Detalhes das regras

• Apenas respostas 2xx bem-sucedidas são cobradas.
• Operações indisponíveis fora da cobertura (como redes não compatíveis ou blocos fora da cobertura de traces) retornam HTTP 422 no_coverage, que não é cobrado, mas conta para os limites de taxa.
• Respostas HTTP 401, 402, 404 e 429 não são cobradas. Para cabeçalhos de resposta (x-bv-meter: 1), consulte Códigos de status HTTP e regras de cobrança.

Tabela de códigos de status da Data API

Consultar saldo (GET /v1/account)

O titular de uma API key pode verificar detalhes de saldo e cota da chave diretamente, sem incorrer em nenhuma cobrança ou dedução de Compute Units (CU):

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

• Gratuito e não cobrado: GET /v1/account é gratuito. Nunca é cobrado, não deduz CU e retorna HTTP 200 com o saldo atual mesmo quando ele é zero ou negativo (nunca retorna 402).
• Autenticação: a autenticação da chave usa exclusivamente o cabeçalho x-api-key (chaves de caminho e tokens Bearer não são aceitos). Cabeçalho ausente retorna 401 missing_api_key; chaves inválidas ou revogadas retornam 401 invalid_api_key. (Chaves expiradas retornam 403 key_expired; indisponibilidades temporárias do serviço retornam 503 auth_unavailable ou billing_unavailable com Retry-After.)
• Limite de taxa: possui um limite independente de 5 requisições por segundo por ID de chave, independente da medição de CU e cobrança. Exceder o limite retorna HTTP 429 rate_limited com um cabeçalho Retry-After.

Campos de resposta:

• key_id: a string de identificador da API key.
• plan: tipo de plano da conta (free quando a conta tem franquia de taxa de chamadas do plano gratuito; paid caso contrário).
• balance_units: saldo restante da conta em unidades (pode ser zero ou negativo).
• balance_cu: saldo restante convertido para Compute Units (CU).
• balance_as_of_age_ms: milissegundos decorridos desde que o saldo foi lido da fonte de dados.
• key: limites específicos da chave e detalhes de cota:
  • cu_per_sec: taxa de recarga do token-bucket em CU por segundo.
  • burst_cu: capacidade de rajada do token-bucket em CU.
  • cu_cap: limite de CU vitalício para esta chave ou null se não houver limite.
  • cu_cap_remaining: CU restante sob cu_cap ou null se não houver limite (pode ser zero ou negativo).
  • expires_at: timestamp de expiração RFC 3339 ou null se a chave nunca expirar.

Exemplo de resposta:

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

Preços e upgrades

O custo específico de todas as chamadas faturadas é determinado pelos pesos de CU publicados:

• Para verificar os pesos de todos os métodos e operações, consulte a tabela de pesos de métodos e as Regras de medição de CU para JSON-RPC.
• Para preços de planos e detalhes de liquidação, consulte a página de preços.
• Upgrade para um plano pago: realizar uma recarga paga remove o limite de chamadas por segundo do plano gratuito; cada chave permanece sujeita aos limites de taxa e rajada de CU.

Processo de recarga on-chain

Quando o saldo da sua conta for insuficiente ou você precisar de maior capacidade, recarregue on-chain no console seguindo estes passos:

1. Entre no console: faça login no Console BlockVectra.
2. Acesse a página de faturamento: navegue até a página de faturamento.
3. Obtenha seu endereço dedicado: no cartão de recarga on-chain, copie o endereço de recarga dedicado da sua conta ou escaneie o código QR.
4. Transfira fundos: transfira apenas usando as redes compatíveis e as USDC / USDT / USDG listadas na página. Redes compatíveis e valores mínimos de recarga são mostrados no console.
5. Crédito automático: assim que detectadas on-chain, as transações aparecem como "Processando"; uma vez confirmados, os créditos são adicionados automaticamente ao seu saldo.

Observações importantes:

• Use apenas as redes e tokens explicitamente listados no console. Transferências em redes não compatíveis ou com tokens incorretos não podem ser creditadas automaticamente.
• Certifique-se de que cada transferência atinja o valor mínimo de recarga indicado no console.
• Assim que sua primeira recarga paga for creditada, sua conta será atualizada para uma conta paga, removendo o limite de chamadas por segundo do plano gratuito.

Programas de agentes ou servidores podem chamar diretamente os endpoints de recarga usando uma API key; consulte o guia de recarga programática para agentes.

Cobrança de push por Webhook

O Push tem pesos separados para eventos de dados entregues, consultas de histórico bem-sucedidas e endereços-dia cobrados. Chamadas de gerenciamento além do histórico de eventos, tentativas de entrega com falha, novas tentativas automáticas e eventos de controle são gratuitas. Cada evento entregue é cobrado uma vez; replays do cliente e eventos canônicos entregues novamente após uma reorganização são novas entregas cobradas. As cobranças de endereço usam a contagem máxima de endereços de cada assinatura enquanto esteve online durante o dia UTC; a franquia de endereços gratuitos da conta é compartilhada entre as assinaturas, sendo utilizada primeiro pelas assinaturas mais antigas. Um endereço em duas assinaturas é contado duas vezes; adicionar redes altera as taxas de eventos, não as taxas de endereço.

Consulte o guia da API de Webhook de blockchain para configuração, verificação de assinaturas e recuperação de entregas. O guia de pagamentos com stablecoins aborda a validação de recibos e preenchimento por polling; as assinaturas WebSocket usam sua própria medição de conexões e notificações. Os erros de requisição estão listados na referência de erros. Os pesos abaixo são obtidos de GET /v1/plans.

Próximos passos

• Explore o diretório de conjuntos de dados para ver todos os conjuntos de dados indexados pela BlockVectra.
• Consulte o plano gratuito e os preços para verificar o que sua conta inclui.
• Entre no console para criar uma API key.