# Referência de erros

> Source: https://docs.blockvectra.com/pt-br/errors/

Esta referência documenta todos os códigos de erro e valores `reason` legíveis por máquina nos serviços BlockVectra, incluindo se uma chamada rejeitada é cobrada, políticas de novas tentativas, tempos de backoff e ações recomendadas para agentes de IA e clientes automatizados.

Para consumo por máquina, obtenha o catálogo completo em JSON em [/errors.json](https://docs.blockvectra.com/errors.json). Cada resposta de erro com `docs_url` aponta diretamente para uma âncora estável nesta página: `https://docs.blockvectra.com/en/errors/#<reason>` (ou `#-<code-number>` para erros sem código de motivo).

### Erros JSON-RPC



| HTTP | Código | Motivo | Significado | Cobrado | Permite nova tentativa | Tempo de espera (Retry-After) | Ação do agente |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 401 | -32024 | `missing_api_key` | API key ausente: envie-a no caminho da requisição (/v1/{chain}/<api_key>) ou no cabeçalho x-api-key | Não | Não | — | Para endpoints JSON-RPC (/v1/{chain}), forneça a API key no caminho da requisição (/v1/{chain}/<api_key>) ou no cabeçalho x-api-key. Para a Top-up API (/v1/topup/*), forneça a API key apenas no cabeçalho x-api-key. |
| 401 | -32024 | `invalid_api_key` | API key desconhecida, desativada ou revogada: JSON-RPC e Data API retornam HTTP 401 com um envelope de erro invalid_api_key (JSON-RPC: error.code -32024 e error.data.reason invalid_api_key; Data API: error.code e error.data.reason invalid_api_key). | Não | Não | — | Verifique a API key; se necessário, entre novamente no console ou pelo cadastro programático para criar uma nova API key (consulte [Perdeu sua sessão ou API key?](https://docs.blockvectra.com/en/guides/programmatic-signup/#lost-your-session-or-api-key)). |
| 403 | -32025 | `key_expired` | API key expirada; crie uma nova API key no console | Não | Não | — | API key expirada; crie uma nova API key no console ou pelo cadastro programático. |
| 403 | -32025 | `key_cap_exhausted` | Limite de CU da API key esgotado; crie uma nova API key no console | Não | Não | — | Limite vitalício de CU da API key esgotado; crie uma nova API key no console ou pelo cadastro programático. |
| 503 | -32021 | `auth_unavailable` | Dados de autenticação temporariamente indisponíveis | Não | Sim | Respeite o cabeçalho Retry-After (segundos) | O servidor está temporariamente impossibilitado de verificar API keys; isso não é um problema com sua API key. Aguarde conforme Retry-After e tente novamente; **não recrie a API key**. |
| 404 | -32600 | `unknown_chain` | Rede desconhecida | Não | Não | — | Consulte as redes disponíveis com GET /v1/chains ou a ferramenta list_chains; verifique o caminho da URL. |
| 404 | 404 | `unknown_endpoint` | O método e o caminho da Data API não correspondem a uma operação conhecida | Não | Não | — | Verifique o método e o caminho da URL na documentação da Data API. |
| 200 | -32700 | `parse_error` | Erro de interpretação do JSON | Não | Não | — | Verifique a sintaxe JSON válida no corpo da requisição antes de enviar. |
| 200 | -32600 | `invalid_request` | Requisição inválida | Não | Não | — | Inspecione a estrutura da requisição; verifique os campos jsonrpc: '2.0', id e method antes de reenviar. |
| 200 | -32602 | `invalid_params` | Tracer não permitido | Não | Não | — | Ajuste os parâmetros do método; verifique os tracers compatíveis e os limites de timeout da rede. |
| 200 | -32602 | `logs_range_too_large` | Intervalo de blocos do eth_getLogs muito grande: máximo de <N> blocos | Não | Não | — | Reduza o intervalo de blocos da consulta para o max_logs_block_range indicado em GET /v1/chains. |
| 429 | -32005 | `public_rate_limit` | Limite de taxa de requisições públicas ultrapassado | Não | Sim | Respeite o cabeçalho Retry-After (segundos) | Aguarde conforme o cabeçalho Retry-After e tente novamente ou envie a requisição com uma API key. [Obter uma API key](https://blockvectra.com/en/get-api-key/?ref=err-public). |
| 429 | -32005 | `public_pool_busy` | Pool público da rede ocupado | Não | Sim | Respeite o cabeçalho Retry-After ou aguarde alguns segundos e tente novamente com backoff | Tente novamente com backoff ou envie a requisição com uma API key. [Obter uma API key](https://blockvectra.com/en/get-api-key/?ref=err-public). |
| 200 | -32601 | `method_not_public` | Método indisponível no endpoint público | Não | Não | — | Use um método compatível com o endpoint público ou envie a requisição com uma API key. [Obter uma API key](https://blockvectra.com/en/get-api-key/?ref=err-public). |
| 200 | -32601 | `method_not_allowed` | Método indisponível nesta rede ou desativado por política | Não | Não | — | Verifique methods.allow e methods.deny em GET /v1/chains para os métodos compatíveis. O suporte ao envio de transações é determinado por methods.allow em GET /v1/chains. O envio de transações está atualmente indisponível em: HyperEVM. |
| 200 | -32601 | `subscription_not_available` | Assinatura WebSocket não oferecida nesta rede | Não | Não | — | Verifique as assinaturas disponíveis para esta rede em GET /v1/chains. |
| 200 | -32602 | `logs_filter_required` | A assinatura de logs exige um endereço ou topic0 (valor não nulo na primeira posição de topics) | Não | Não | — | Especifique um endereço ou topic0 não nulo no filtro de logs. |
| 200 | -32600 | `batch_too_large` | Lote muito grande: máximo de <N> chamadas | Não | Não | — | Divida o lote em lotes menores que atendam ao limite máximo de chamadas indicado nos dados do erro. |
| 413 | 413 | `request_too_large` | Corpo da requisição Data API ultrapassa o limite de tamanho | Não | Não | — | Reduza o tamanho do corpo da requisição. |
| 200 | -32000 | `not_found` | Transação não encontrada | Não | Não | — | Se foi enviada ou minerada recentemente, aguarde a propagação e tente novamente; caso contrário, verifique o número ou hash do bloco. |
| 200 | -32011 | `state_window` | Estado histórico indisponível além dos <N> blocos mais recentes | Não | Não | — | Consulte blocos dentro de state_window_blocks informado por GET /v1/chains ou use a Data API para dados históricos. |
| 200 | -32011 | `range_not_indexed` | Histórico solicitado não está completamente indexado | Não | Não | — | Reduza a consulta histórica a um intervalo indexado; não repita o mesmo intervalo sem cobertura sem alterações. |
| 200 | -32011 | `history_not_ready` | Histórico solicitado ainda não está pronto | Não | Sim | Aguarde a indexação alcançar os dados; respeite error.data.retry_after_seconds quando presente | Tente novamente quando a indexação alcançar os dados, aguardando error.data.retry_after_seconds quando fornecido. |
| 429 | -32005 | `key_rate_limit` | Limite de taxa ultrapassado | Não | Sim | Respeite o cabeçalho Retry-After (segundos) | Aguarde o tempo especificado no cabeçalho Retry-After antes de tentar novamente ou distribua a carga. |
| 429 | rate_limited | `rate_limited` | Limite de taxa de requisições ultrapassado na API ou em GET /v1/account (mais de 5 requisições por segundo para esta API key) | Não | Sim | Respeite o cabeçalho Retry-After (segundos) | Aguarde o tempo de Retry-After antes de tentar novamente. |
| 429 | -32005 | `concurrency_limit` | Limite de taxa ultrapassado | Não | Sim | Respeite o cabeçalho Retry-After ou aguarde as chamadas ativas terminarem | Limite o tamanho do pool de concorrência do cliente e tente novamente nos slots liberados. |
| 429 | -32005 | `free_plan_call_limit` | Limite de taxa ultrapassado | Não | Sim | Aguarde 1 segundo antes de tentar novamente | Reduza a taxa de requisições ou faça uma recarga para liberar a capacidade do plano pago. |
| 429 | -32022 | `request_exceeds_burst` | O custo da requisição de <N> CU ultrapassa a capacidade de burst de <M> CU | Não | Não | — | Aguardar não resolverá; divida o lote ou reduza os parâmetros do método para ficar dentro da capacidade de burst. |
| 429 | -32022 | `free_plan_batch_too_large` | A requisição tem <N> chamadas, ultrapassando o limite do plano gratuito de <M> chamadas por segundo | Não | Não | — | Aguardar não resolverá; divida o lote para ficar dentro do limite de chamadas do plano gratuito ou faça uma recarga. |
| 429 | -32005 | `ws_connection_limit` | Limite de conexões WebSocket atingido para esta API key ou conta | Não | Não | — | Feche uma conexão WebSocket não utilizada ou reutilize uma conexão existente. |
| 200 | -32022 | `subscription_limit` | Limite de assinaturas WebSocket atingido para esta conexão | Não | Não | — | Cancele uma assinatura existente ou abra outra conexão. |
| 200 | -32005 | `ws_filter_capacity` | Filtros de logs WebSocket estão no limite de capacidade | Não | Não | — | Cancele uma assinatura de logs existente ou use um filtro mais restrito. |
| 200 | -32026 | `ws_push_overloaded` | Fila de notificações WebSocket sobrecarregada | Não | Sim | Tente novamente mais tarde com backoff ou reconecte | Repita eth_subscribe com backoff exponencial ou reconecte. Assinaturas existentes continuam recebendo notificações. |
| 200 | -32005 | `overloaded` | Serviço sobrecarregado, tente novamente mais tarde | Não | Sim | Aguarde alguns segundos e tente novamente com backoff exponencial | Aplique backoff com jitter e repita a requisição. |
| 402 | -32020 | `balance_exhausted` | Saldo insuficiente (quando o saldo é conhecido, error.data inclui balance_units e balance_cu) | Não | Não | — | Recarregue on-chain: obtenha seu endereço de depósito no Console ou em `GET /v1/topup/deposit-address` (MCP `get_deposit_address`); consulte o [guia de recarga para agentes](https://docs.blockvectra.com/en/guides/agent-topup/) ou use a renovação de cota no console se elegível. Quando o saldo é conhecido, error.data contém balance_units (negativo quando há saldo devedor) e balance_cu. |
| 402 | -32020 | `free_grant_exhausted` | Créditos gratuitos esgotados (quando o saldo é conhecido, error.data inclui balance_units e balance_cu) | Não | Não | — | Recarregue on-chain: obtenha seu endereço de depósito no Console ou em `GET /v1/topup/deposit-address` (MCP `get_deposit_address`); consulte o [guia de recarga para agentes](https://docs.blockvectra.com/en/guides/agent-topup/), use a renovação de cota se disponível ou aguarde os créditos do próximo ciclo. Quando o saldo é conhecido, error.data contém balance_units (negativo quando há saldo devedor) e balance_cu. |
| 503 | -32021 | `billing_unavailable` | Dados de cobrança temporariamente indisponíveis | Não | Sim | Respeite o cabeçalho Retry-After (segundos) | Isso não é um problema de saldo; API keys novas sincronizam em segundos. Aguarde conforme Retry-After e tente novamente. |
| 200 | -32010 | `node_syncing` | O nó está sincronizando; chamadas temporariamente indisponíveis | Não | Sim | Aguarde alguns segundos e tente novamente | Aguarde a conclusão da sincronização do nó ou consulte GET /v1/status. |
| 200 | -32603 | `upstream_unavailable` | Upstream indisponível | Não | Sim | Aguarde alguns segundos e tente novamente | Tente novamente com backoff exponencial; consulte GET /v1/status para verificar o estado do nó. |
| 504 | 504 | `upstream_timeout` | Serviço upstream não respondeu dentro do limite de tempo | Não | Sim | Tente novamente após uma breve espera | Repita a requisição com backoff exponencial. |
| 200 | -32000 | `response_too_large` | Resposta upstream muito grande | Não | Não | — | Restrinja os parâmetros da consulta (por exemplo, reduza o intervalo de blocos em eth_getLogs ou solicite traces menores). |
| 200 | -32603 | `internal_error` | Erro interno do serviço | Não | Não | — | Repita a requisição; informe falhas persistentes ao suporte com o horário. |
| 200 | 4444 | — | Histórico removido por pruning indisponível | Não | Não | — | O bloco está fora da janela de histórico retida pelo nó; consulte blocos históricos pela Data API. |
| 200 | -32000 | — | historical state ... is not available; old data not available due to pruning... | Não | Não | — | Consulte blocos dentro da janela de estado ou use a Data API para consultas históricas. |
| 200 | -32002 | — | <node message> | Não | Sim | Aguarde alguns segundos e tente novamente com um lote menor | Reduza a quantidade de chamadas do lote e tente novamente. |
| 200 | -32003 | — | <node message> | Não | Não | — | Divida o lote em requisições menores para reduzir o tamanho da resposta. |
| 200 | -32601 | — | <node message> | Não | Não | — | Verifique methods.allow e methods.deny em GET /v1/chains para os métodos compatíveis. O suporte ao envio de transações é determinado por methods.allow em GET /v1/chains. O envio de transações está atualmente indisponível em: HyperEVM. |
| 200 | -32603 | — | <node message> | Não | Sim | Tente novamente após uma breve espera | Repita a requisição; informe falhas persistentes ao suporte com o horário. |
| 200 | -32600 | — | <node message> | Não | Não | — | Inspecione as requisições individuais do lote para parâmetros fora da especificação; divida e tente novamente. |
| 200 | * | — | <node message> | Sim | Não | — | O nó executou computação e houve cobrança. Inspecione o motivo/dados da reversão ou os parâmetros da chamada; não repita às cegas. |
| 408 | 408 | — | A requisição excedeu 35s entre a conclusão dos cabeçalhos e a resposta | Possível | Sim | Aguarde alguns segundos antes de repetir chamadas de leitura | As chamadas podem ter chegado ao nó e ser cobradas. Para leituras, tente novamente com backoff. Para escritas (por exemplo, eth_sendRawTransaction), verifique primeiro o status da transação pelo hash. |

### Códigos de fechamento de WebSocket

Códigos de fechamento de conexão WebSocket e ações recomendadas para o cliente.

| Código | Motivo | Significado | Permite nova tentativa | Tempo de espera (Retry-After) | Ação do agente |
| --- | --- | --- | --- | --- | --- |
| 1001 | — | Conexão ociosa | Sim | Reconecte conforme necessário | Reconecte conforme necessário. |
| 1003 | — | Frames binários não são aceitos | Não | — | Não reconecte automaticamente; envie apenas frames de texto UTF-8. |
| 1009 | — | Mensagem muito grande | Não | — | Não reconecte automaticamente; divida requisições grandes para ficar abaixo de 1 MiB. |
| 1012 | — | Reinício do serviço | Sim | Reconecte com backoff e jitter | Reconecte com backoff e jitter, refaça as assinaturas e recupere dados perdidos. |
| 1013 | — | Rede indisponível; sobrecarga | Sim | Reconecte com backoff exponencial e full jitter | Reconecte com backoff exponencial e full jitter, refaça as assinaturas e recupere dados perdidos. |
| 4402 | — | Saldo insuficiente | Não | — | Não reconecte automaticamente; recarregue on-chain: obtenha seu endereço de depósito no Console ou em `GET /v1/topup/deposit-address` (MCP `get_deposit_address`); consulte o [guia de recarga para agentes](https://docs.blockvectra.com/en/guides/agent-topup/) ou use a renovação de cota no console se elegível. |
| 4404 | — | API key inválida | Não | — | Não reconecte automaticamente; verifique ou rotacione a API key no console. |
| 4408 | — | O serviço fecha uma sessão cuja fila de Push ultrapassa 512 KiB (524,288 bytes) e descarta notificações pendentes; clientes podem não receber um frame de fechamento (o navegador informa 1006); trate desconexões inesperadas como 4408. | Sim | Reconecte com backoff; reduza assinaturas ou leia mais rápido | Clientes devem tratar uma queda inesperada (sem frame de fechamento, navegador informa 1006) como 4408: reconecte com backoff, restabeleça assinaturas e recupere dados descartados com eth_getLogs; reduza as assinaturas ou leia mais rápido. |
| 4429 | — | Taxa de Push ultrapassada | Sim | Reconecte com backoff ou reduza assinaturas | Reduza as assinaturas ou reconecte com backoff. |
| 4503 | — | Cobrança indisponível | Sim | Reconecte com backoff exponencial e full jitter | Reconecte com backoff exponencial e full jitter e refaça as assinaturas. |

### Erros da Data API

Erros retornados pelos endpoints da Data API de blockchain em /v1/data/{chain}/.

| HTTP | Código | Motivo | Significado | Cobrado | Permite nova tentativa | Tempo de espera (Retry-After) | Ação do agente |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 400 | bad_request | — | Parâmetro de consulta duplicado, query string inválida ou requisição malformada | Não | Não | — | Inspecione os parâmetros de consulta; garanta que parâmetros como limit apareçam no máximo uma vez e sejam válidos. |
| 409 | not_indexed_yet | — | Número de bloco ou janela solicitada acima de as_of_block, ou hash aponta acima de as_of_block (inclui indexed_through, exceto quando a rede não tem blocos indexados) | Não | Sim | Aguarde alguns segundos até indexed_through alcançar o bloco | Consulte até que o bloco solicitado ou to_block seja igual ou inferior a indexed_through ou aguarde a rede começar a gravar blocos. |
| 409 | window_too_large | — | Janela de blocos maior que 100,000 blocos e parâmetro clamp não definido como true | Não | Não | — | Reduza o intervalo de blocos (from_block a to_block) para <= 100,000 blocos ou envie clamp=true. |
| 409 | too_many_pools | — | Token corresponde a mais de 200 pools de liquidez; consulte por pool | Não | Não | — | Consulte um endereço de pool específico em vez de todos os pools do token. |
| 409 | span_exceeded | — | Intervalo de datas solicitado ultrapassa o máximo de 90 dias | Não | Não | — | Reduza o intervalo de datas entre from_time e to_time para até 90 dias. |
| 422 | no_coverage | — | Recurso não compatível com esta rede ou bloco solicitado anterior à janela de cobertura | Não | Não | — | Verifique `features` e `coverage.from_block` em GET /v1/data/chains (ou `data_features` no GET /v1/status gratuito) antes de consultar. |
| 503 | unavailable | — | Serviço de dados temporariamente indisponível | Não | Sim | Aguarde alguns segundos e tente novamente com backoff exponencial | Tente novamente após uma breve espera com backoff exponencial. |
| 402 | insufficient_balance | — | Saldo pago ou créditos gratuitos esgotados (quando o saldo é conhecido, error.data inclui balance_units e balance_cu) | Não | Não | — | Recarregue on-chain: obtenha seu endereço de depósito no Console ou em `GET /v1/topup/deposit-address` (MCP `get_deposit_address`); consulte o [guia de recarga para agentes](https://docs.blockvectra.com/en/guides/agent-topup/) ou aguarde a renovação da franquia gratuita. |
| 429 | cost_exceeds_burst | — | Uma requisição custa mais que a capacidade de burst da API key | Não | Não | — | Divida a requisição em menores; repeti-la como foi enviada nunca terá sucesso. |
| 503 | gateway_overloaded | — | Capacidade da Data API temporariamente indisponível | Não | Sim | Retry-After: 1 segundo | Reduza as requisições simultâneas entre API keys e redes desta conta; aguarde Retry-After antes de tentar novamente. error.data.reason é null. |

### Erros das APIs de console, conta e faucet

Erros retornados pelos endpoints de gestão, provisionamento de API keys, autenticação e faucet em /v1/.

| HTTP | Código | Motivo | Significado | Cobrado | Permite nova tentativa | Tempo de espera (Retry-After) | Ação do agente |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 409 | topup_disabled | — | Recarga pausada ou nenhuma rede disponível para recarga no momento; novos endereços não podem ser alocados, mas endereços já alocados continuam atribuídos à conta | Não | Não | — | Verifique a disponibilidade de recarga em GET /v1/topup/status; tente novamente quando a recarga estiver habilitada. |
| 503 | deposit_unavailable | — | Temporariamente impossível alocar um endereço de depósito; tente novamente conforme o cabeçalho Retry-After | Não | Sim | Respeite o cabeçalho Retry-After (segundos) e use backoff exponencial | Tente novamente conforme o cabeçalho Retry-After com backoff exponencial. |
| 400 | invalid_request | `invalid_username` | Formato de nome de usuário inválido (deve conter caracteres alfanuméricos ou underscores) | Não | Não | — | Forneça um nome de usuário válido conforme os requisitos de caracteres e comprimento. |
| 400 | invalid_request | `expires_at` | Data de expiração da API key não está no futuro ou ultrapassa o período máximo permitido de validade | Não | Não | — | Defina expires_at como um timestamp RFC 3339 futuro dentro do período de validade permitido (padrão de 365 dias) ou use expires_in_secs. |
| 400 | invalid_request | `cu_cap` | Parâmetro cu_cap fora dos limites (deve ser um inteiro entre 1 e 9007199254740991) | Não | Não | — | Ajuste cu_cap para um inteiro entre 1 e 9007199254740991 ou omita-o para CU ilimitadas. |
| 400 | siwe_invalid | `expired` | Mensagem Sign-In with Ethereum (SIWE) expirada ou nonce já utilizado | Não | Sim | Obtenha um novo desafio imediatamente e assine | Solicite um novo desafio em /v1/auth/siwe/challenge e assine a declaração recém-emitida. |
| 400 | siwe_invalid | `chain_mismatch` | chainId da mensagem SIWE não corresponde à configuração do servidor | Não | Não | — | Use o chainId retornado por /v1/auth/siwe/challenge ao construir a mensagem SIWE. |
| 400 | siwe_invalid | `domain_mismatch` | Domínio da mensagem SIWE não corresponde ao host do servidor | Não | Não | — | Garanta que domain e uri correspondam ao host do servidor retornado no desafio. |
| 400 | siwe_invalid | `signature` | Falha na verificação criptográfica da assinatura SIWE | Não | Não | — | Verifique se a mensagem foi assinada pela chave privada correspondente ao endereço especificado. |
| 409 | key_limit_reached | `active_keys` | API keys ativas (não revogadas) atingiram o limite máximo da conta | Não | Não | — | Revogue uma API key existente não utilizada antes de criar uma nova. |
| 409 | no_reset_available | `nothing_to_reset` | Saldo já igual ou superior à meta de renovação; oportunidade de renovação preservada | Não | Não | — | Nenhuma renovação necessária no momento; use a oportunidade de renovação após esgotar o saldo. |
| 429 | rate_limited | `daily_creations` | Limite de criação de API keys em 24 horas da conta atingido | Não | Sim | Respeite o cabeçalho Retry-After (segundos) | Rotacione API keys existentes em vez de criar novas ou aguarde a renovação da janela de 24 horas. |
| 429 | signup_rate_limited | `per_ip` | Limite de taxa de cadastro atingido para a sub-rede IP do cliente | Não | Sim | Respeite o cabeçalho Retry-After (segundos) | Aguarde o intervalo Retry-After antes de criar uma nova conta a partir desta rede. |
| 429 | signup_rate_limited | `global` | Limite global de taxa de cadastro de novos usuários atingido em todas as origens | Não | Sim | Respeite o cabeçalho Retry-After (segundos) | Aguarde o intervalo Retry-After antes de tentar criar a conta novamente. |
| 400 | oauth_invalid | — | Parâmetro OAuth inválido ou estado de callback desconhecido, expirado ou já utilizado | Não | Sim | — | Inicie um novo fluxo de login OAuth em /v1/auth/{provider}/start. |
| 400 | login_code_invalid | — | Código de login desconhecido, expirado, já consumido ou verificador PKCE não corresponde | Não | Não | — | Reinicie o login para obter um novo código de login. |
| 401 | unauthenticated | — | Sessão ausente ou token de sessão inválido, expirado ou revogado; na Top-up API (/v1/topup/*), também ocorre quando o cabeçalho Authorization contém um token não Bearer ou inválido em vez de x-api-key | Não | Não | — | Entre novamente para obter um novo token de sessão Bearer; na Top-up API, use o cabeçalho de requisição x-api-key em vez de Authorization para enviar a API key. |
| 403 | user_disabled | — | Conta suspensa pela administração | Não | Não | — | Entre em contato com contact@blockvectra.com para suporte à conta. |
| 404 | provider_disabled | — | Provedor OAuth reconhecido, mas atualmente desativado | Não | Não | — | Use SIWE ou outro provedor de autenticação compatível. |
| 409 | identity_in_use | — | Identidade (carteira ou conta OAuth) já vinculada a outro usuário | Não | Não | — | Desvincule a identidade da conta anterior ou use outra identidade. |
| 409 | identity_limit_reached | — | Quantidade máxima de identidades vinculadas (5) atingida para esta conta | Não | Não | — | Desvincule uma identidade desnecessária antes de vincular uma nova. |
| 409 | last_identity | — | Não é possível desvincular a única identidade restante da conta | Não | Não | — | Vincule outra identidade antes de remover esta. |
| 409 | key_not_active | — | Tentativa de rotacionar uma API key desativada, revogada ou expirada | Não | Não | — | Crie uma nova API key ou rotacione uma API key ativa. |
| 409 | no_reset_available | — | Nenhuma oportunidade de renovação de cota restante nesta conta | Não | Não | — | Recarregue on-chain: obtenha seu endereço de depósito no Console ou em `GET /v1/topup/deposit-address` (MCP `get_deposit_address`); consulte o [guia de recarga para agentes](https://docs.blockvectra.com/en/guides/agent-topup/) ou aguarde o próximo ciclo promocional. |
| 413 | payload_too_large | — | Corpo da requisição ultrapassa o limite de tamanho de 64 KiB | Não | Não | — | Reduza o tamanho do corpo da requisição para menos de 64 KiB. |
| 503 | signup_paused | — | Cadastros globais de novos usuários temporariamente pausados; logins existentes não são afetados | Não | Sim | Tente o cadastro novamente mais tarde | Cadastros de novos usuários temporariamente pausados; verifique o status e tente novamente mais tarde. |
| 503 | usage_unavailable | — | Serviço de relatórios de uso temporariamente indisponível | Não | Sim | Aguarde alguns segundos e tente novamente | Afeta apenas o endpoint /usage; outros endpoints funcionam normalmente. Tente novamente em breve. |
| 500 | internal | — | Erro inesperado do servidor | Não | Sim | Tente novamente após uma breve espera | Repita a requisição com backoff exponencial. |
| 400 | invalid_address | `invalid_address` | Formato ou checksum do endereço de destinatário inválido | Não | Não | — | Use 0x seguido de 40 caracteres hexadecimais, em minúsculas ou com checksum EIP-55; verifique data.field (/address). |
| 503 | faucet_empty | `faucet_empty` | O faucet tem fundos insuficientes para a solicitação e a tarifa da transação | Não | Sim | Respeite o cabeçalho Retry-After (segundos) | Aguarde Retry-After antes de tentar novamente; não presuma que ETH de teste foi enviado sem uma resposta de aceitação. |
| 503 | service_unavailable | `service_unavailable` | Processamento de solicitações do faucet temporariamente indisponível ou solicitação anterior ainda sem recibo | Não | Sim | Respeite o cabeçalho Retry-After (segundos) | Aguarde Retry-After antes de tentar novamente; não presuma que ETH de teste foi enviado sem uma resposta de aceitação. |

### Erros da Push API

Erros de gestão de assinaturas de Webhook e histórico de eventos em /v1/push/.

| HTTP | Código | Motivo | Significado | Cobrado | Permite nova tentativa | Tempo de espera (Retry-After) | Ação do agente |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 400 | invalid_request | — | Campos da requisição, endereços, paginação ou intervalo de blocos inválidos. | Não | Não | — | Inspecione data.field e data.invalid; corrija a requisição. |
| 401 | missing_api_key | — | x-api-key ausente. | Não | Não | — | Forneça sua API key em x-api-key. |
| 401 | invalid_api_key | — | API key desconhecida, desativada ou revogada. | Não | Não | — | Use uma API key ativa da sua conta. |
| 402 | insufficient_balance | — | Saldo ou franquia gratuita esgotados para o histórico de eventos. | Não | Não | — | Inspecione data.reason (balance_exhausted ou free_grant_exhausted) e data.balance_units / data.balance_cu quando presentes; recarregue via data.topup_url ou data.deposit_address_url. |
| 403 | key_cap_exhausted | — | Limite de CU da API key esgotado para o histórico de eventos. | Não | Não | — | Inspecione data.cu_cap e crie uma nova API key no console. |
| 403 | key_expired | — | API key expirada. | Não | Não | — | Use uma API key não expirada da sua conta. |
| 404 | not_found | — | Rota, método ou assinatura não encontrados. | Não | Não | — | Verifique o caminho, o método e a conta proprietária da assinatura. |
| 409 | limit_reached | — | Limite de assinaturas ou pares de endereço da conta atingido. | Não | Não | — | Inspecione data.limit e data.max; reduza assinaturas ou endereços. |
| 413 | request_too_large | — | Corpo da requisição ultrapassa o limite da rota. | Não | Não | — | Divida o lote de endereços ou reduza o tamanho do corpo. |
| 422 | chain_not_available | — | Rede indisponível para Push ou ausente da assinatura. | Não | Não | — | Verifique GET /v1/push/chains e as redes da assinatura. |
| 422 | chains_required | — | É necessária pelo menos uma rede. | Não | Não | — | Forneça um objeto chains não vazio; use o status offline para parar de monitorar. |
| 422 | confirmations_out_of_range | — | Profundidade de confirmação fora do intervalo da rede. | Não | Não | — | Escolha confirmations entre data.min e data.max. |
| 422 | destination_not_allowed | — | URL de recebimento não permitida. | Não | Não | — | Inspecione data.rule; use um hostname HTTPS na porta 443 sem userinfo ou fragmento. |
| 422 | block_out_of_range | — | Intervalo de blocos fora da cobertura disponível de replay ou histórico. | Não | Não | — | Use data.min_block e data.max_block para ajustar o intervalo. |
| 429 | cost_exceeds_burst | — | Custo da requisição de histórico ultrapassa a capacidade de burst da API key. | Não | Não | — | Inspecione data.reason (request_exceeds_burst) e data.max; aumente a capacidade de burst antes de tentar novamente. Repetir sem alterações não ajuda. |
| 429 | rate_limited | — | Limite de taxa de gestão ou consulta de histórico atingido. | Não | Sim | Aguarde os segundos de Retry-After. | Para histórico, inspecione data.reason (key_rate_limit ou free_plan_call_limit); aguarde os segundos de Retry-After e reduza a frequência ou concorrência das requisições. |
| 500 | internal_error | — | Erro inesperado do serviço. | Não | Não | — | Guarde x-request-id e entre em contato com o suporte. |
| 503 | auth_unavailable | — | Validação de API key temporariamente indisponível. | Não | Sim | Aguarde os segundos de Retry-After. | Aguarde os segundos de Retry-After antes de tentar novamente. |
| 503 | billing_unavailable | — | Estado de cobrança de histórico temporariamente indisponível. | Não | Sim | Aguarde os segundos de Retry-After. | Aguarde os segundos de Retry-After antes de tentar novamente. |
| 503 | upstream_unavailable | — | Serviço Push temporariamente inacessível. | Não | Sim | Aguarde os segundos de Retry-After. | Aguarde os segundos de Retry-After antes de tentar novamente. |
| 503 | service_unavailable | — | Serviço Push ou capacidade de endereços temporariamente indisponível. | Não | Sim | Aguarde os segundos de Retry-After. | Aguarde os segundos de Retry-After antes de tentar novamente. |

Para erros de assinatura ou replay de Webhook, siga o [guia de recuperação de entregas Push](https://docs.blockvectra.com/en/guides/webhook-push/#delivery-retries-and-replay). A integração do receptor começa pela [verificação de assinatura no corpo bruto](https://docs.blockvectra.com/en/guides/webhook-push/#verify-signatures); o [exemplo de pagamentos com stablecoins](https://docs.blockvectra.com/en/guides/stablecoin-payments/#receive-payments-with-webhooks) adiciona deduplicação de eventos, verificação de recibos, recuperação de lacunas e reconciliação de reorgs. Consulte as [regras de cobrança](https://docs.blockvectra.com/en/guides/billing-rules/#webhook-push-billing) para medição e a [reconexão de WebSocket](https://docs.blockvectra.com/en/guides/websocket-subscriptions/#reconnection-and-exponential-backoff) para assinaturas baseadas em conexão.

Para `logs_range_too_large`, consulte os [parâmetros do método eth\_getLogs](https://docs.blockvectra.com/en/api/json-rpc/methods/eth_getLogs/) e siga o [guia de limites de intervalos de blocos e consultas em partes](https://docs.blockvectra.com/en/guides/getlogs-block-range/).

Para solicitações de faucet na Robinhood Chain, consulte o [guia de faucet da testnet](https://docs.blockvectra.com/en/guides/robinhood-testnet-faucet/) para os critérios de elegibilidade e o tratamento dos códigos de erro compartilhados.