# Referencia de errores

> Source: https://docs.blockvectra.com/es/errors/

Esta referencia documenta todos los códigos de error y valores `reason` legibles por máquina en los servicios de BlockVectra, indicando si una llamada rechazada se factura, políticas de reintento, tiempos de espera con backoff y acciones recomendadas para agentes de IA y clientes automatizados.

Para consumo por máquina, obtenga el catálogo completo en JSON en [/errors.json](https://docs.blockvectra.com/errors.json). Cada respuesta de error con `docs_url` apunta directamente a un ancla estable en esta página: `https://docs.blockvectra.com/en/errors/#<reason>` (o `#-<code-number>` para errores sin código de motivo).

### Errores JSON-RPC



| HTTP | Código | Motivo | Significado | Facturado | Reintentable | Tiempo de espera (Retry-After) | Acción del agente |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 401 | -32024 | `missing_api_key` | API key ausente: envíela en la ruta de la solicitud (/v1/{chain}/<api_key>) o en el encabezado x-api-key | No | No | — | Para endpoints JSON-RPC (/v1/{chain}), proporcione la API key en la ruta de la solicitud (/v1/{chain}/<api_key>) o en el encabezado x-api-key. Para la Top-up API (/v1/topup/*), proporcione la API key únicamente en el encabezado x-api-key. |
| 401 | -32024 | `invalid_api_key` | API key desconocida, deshabilitada o revocada: tanto JSON-RPC como la Data API devuelven HTTP 401 con una estructura de error invalid_api_key (JSON-RPC: error.code -32024 y error.data.reason invalid_api_key; Data API: error.code y error.data.reason invalid_api_key). | No | No | — | Verifique la API key; si es necesario, inicie sesión nuevamente en la consola o mediante el registro programático para crear una nueva API key (consulte [¿Perdió su sesión o API key?](https://docs.blockvectra.com/en/guides/programmatic-signup/#lost-your-session-or-api-key)). |
| 403 | -32025 | `key_expired` | API key expirada; cree una nueva API key en la consola | No | No | — | API key expirada; cree una nueva API key en la consola o mediante el registro programático. |
| 403 | -32025 | `key_cap_exhausted` | Límite de CU de la API key agotado; cree una nueva API key en la consola | No | No | — | Límite vitalicio de CU de la API key agotado; cree una nueva API key en la consola o mediante el registro programático. |
| 503 | -32021 | `auth_unavailable` | Datos de autenticación no disponibles temporalmente | No | Sí | Respete el encabezado Retry-After (segundos) | El servidor no puede verificar las API keys temporalmente; esto no es un problema con su clave. Reintente tras esperar según Retry-After; **no vuelva a crear la API key**. |
| 404 | -32600 | `unknown_chain` | Cadena desconocida | No | No | — | Consulte las cadenas disponibles mediante GET /v1/chains o la herramienta list_chains; verifique la ruta URL. |
| 404 | 404 | `unknown_endpoint` | El método y la ruta de la Data API no coinciden con una operación conocida | No | No | — | Verifique el método y la ruta URL con la documentación de la Data API. |
| 200 | -32700 | `parse_error` | Error de análisis sintáctico de JSON | No | No | — | Verifique que la sintaxis JSON del cuerpo de la solicitud sea válida antes de enviarla. |
| 200 | -32600 | `invalid_request` | Solicitud no válida | No | No | — | Inspeccione la estructura de la solicitud; verifique los campos jsonrpc: '2.0', id y method antes de reenviarla. |
| 200 | -32602 | `invalid_params` | Tracer no permitido | No | No | — | Ajuste los parámetros del método; revise los tracers compatibles y los límites de tiempo de espera para la cadena. |
| 200 | -32602 | `logs_range_too_large` | Rango de bloques de eth_getLogs demasiado amplio: máximo <N> bloques | No | No | — | Reduzca el rango de bloques de la consulta al max_logs_block_range indicado en GET /v1/chains. |
| 429 | -32005 | `public_rate_limit` | Límite de tasa de solicitudes públicas superado | No | Sí | Respete el encabezado Retry-After (segundos) | Espere conforme al encabezado Retry-After y reintente, o envíe la solicitud con una API key. [Obtener una API key](https://blockvectra.com/en/get-api-key/?ref=err-public). |
| 429 | -32005 | `public_pool_busy` | El grupo público de la cadena está ocupado | No | Sí | Respete el encabezado Retry-After o espere unos segundos y reintente con backoff | Reintente con backoff o envíe la solicitud con una API key. [Obtener una API key](https://blockvectra.com/en/get-api-key/?ref=err-public). |
| 200 | -32601 | `method_not_public` | El método no está disponible en el punto de enlace público | No | No | — | Use un método admitido por el punto de enlace público o envíe la solicitud con una API key. [Obtener una API key](https://blockvectra.com/en/get-api-key/?ref=err-public). |
| 200 | -32601 | `method_not_allowed` | El método no está disponible en esta cadena o ha sido deshabilitado por política | No | No | — | Consulte methods.allow y methods.deny en GET /v1/chains para ver los métodos admitidos. La compatibilidad con el envío de transacciones se determina mediante methods.allow en GET /v1/chains. El envío de transacciones actualmente no está disponible en: HyperEVM. |
| 200 | -32601 | `subscription_not_available` | La suscripción WebSocket no se ofrece en esta cadena | No | No | — | Consulte las suscripciones disponibles para esta cadena mediante GET /v1/chains. |
| 200 | -32602 | `logs_filter_required` | La suscripción a logs requiere una dirección o topic0 (un valor no nulo en la primera posición de topics) | No | No | — | Especifique una dirección o un topic0 no nulo en el filtro de logs. |
| 200 | -32600 | `batch_too_large` | Lote demasiado grande: máximo <N> llamadas | No | No | — | Divida el lote en lotes más pequeños que cumplan con el límite máximo de llamadas indicado en los datos del error. |
| 413 | 413 | `request_too_large` | El cuerpo de la solicitud de la Data API supera el límite de tamaño | No | No | — | Reduzca el tamaño del cuerpo de la solicitud. |
| 200 | -32000 | `not_found` | Transacción no encontrada | No | No | — | Si se envió o minó recientemente, espere a que se propague y reintente; de lo contrario, verifique el número de bloque o el hash. |
| 200 | -32011 | `state_window` | El bloque solicitado está fuera de la ventana de estado admitida para esta cadena (últimos <N> bloques) | No | No | — | Consulte bloques dentro de state_window_blocks, según GET /v1/chains, o utilice la Data API para datos históricos. |
| 200 | -32011 | `range_not_indexed` | El historial solicitado no está completamente indexado | No | No | — | Reduzca el historial solicitado a un rango indexado; no reintente sin cambios el mismo rango sin cobertura. |
| 200 | -32011 | `history_not_ready` | El historial solicitado aún no está listo | No | Sí | Espere a que la indexación alcance los datos; respete error.data.retry_after_seconds cuando esté presente | Reintente cuando la indexación alcance los datos, esperando error.data.retry_after_seconds cuando se proporcione. |
| 429 | -32005 | `key_rate_limit` | Límite de tasa de CU de la API key superado | No | Sí | Respete el encabezado Retry-After (segundos) | Espere los segundos indicados en Retry-After antes de reintentar o distribuya la carga. |
| 429 | rate_limited | `rate_limited` | Límite de tasa de solicitudes superado en la API o GET /v1/account (más de 5 solicitudes por segundo para esta API key) | No | Sí | Respete el encabezado Retry-After (segundos) | Espere el intervalo indicado en Retry-After antes de reintentar. |
| 429 | -32005 | `concurrency_limit` | Límite de solicitudes simultáneas superado para esta API key | No | Sí | Respete el encabezado Retry-After o espere a que finalicen las llamadas activas | Reduzca el número de solicitudes en paralelo o espere a que finalicen las solicitudes en curso. |
| 429 | -32005 | `free_plan_call_limit` | Límite de llamadas por segundo del plan gratuito superado | No | Sí | Espere 1 segundo antes de reintentar | Reduzca la frecuencia de solicitudes o recargue para habilitar el rendimiento del nivel de pago. |
| 429 | -32022 | `request_exceeds_burst` | El costo en CU de la solicitud supera la capacidad máxima de ráfaga (burst) permitida | No | No | — | Esperar no resolverá el problema; divida el lote o reduzca los parámetros del método para ajustarse a la capacidad de ráfaga. |
| 429 | -32022 | `free_plan_batch_too_large` | El tamaño del lote supera el límite para usuarios del plan gratuito | No | No | — | Esperar no resolverá el problema; divida el lote para que se ajuste al límite de llamadas del plan gratuito o realice una recarga. |
| 429 | -32005 | `ws_connection_limit` | Límite de conexiones WebSocket alcanzado para esta clave o cuenta | No | No | — | Cierre una conexión WebSocket no utilizada o reutilice una conexión existente. |
| 200 | -32022 | `subscription_limit` | Límite de suscripciones WebSocket alcanzado para esta conexión | No | No | — | Cancele una suscripción existente o abra otra conexión. |
| 200 | -32005 | `ws_filter_capacity` | Los filtros de logs de WebSocket han alcanzado su capacidad máxima | No | No | — | Cancele una suscripción de logs existente o use un filtro más específico. |
| 200 | -32026 | `ws_push_overloaded` | La cola de notificaciones WebSocket está sobrecargada | No | Sí | Reintente más tarde con backoff o reconéctese | Reintente eth_subscribe con backoff exponencial o reconéctese. Las suscripciones existentes continúan recibiendo notificaciones. |
| 200 | -32005 | `overloaded` | Servicio sobrecargado, reintente más tarde | No | Sí | Espere unos segundos y reintente con backoff exponencial | Aplique backoff con jitter y reintente la solicitud. |
| 402 | -32020 | `balance_exhausted` | Saldo insuficiente (cuando el saldo se conoce, error.data incluye balance_units y balance_cu) | No | No | — | Recargue on-chain: obtenga su dirección de depósito desde la consola o mediante `GET /v1/topup/deposit-address` (MCP `get_deposit_address`); consulte la [guía de recarga para agentes](https://docs.blockvectra.com/en/guides/agent-topup/) o use el restablecimiento de cuota en la consola si es elegible. Cuando se conoce el saldo, error.data incluye balance_units (negativo si está sobregirado) y balance_cu. |
| 402 | -32020 | `free_grant_exhausted` | Créditos gratuitos agotados (cuando el saldo se conoce, error.data incluye balance_units y balance_cu) | No | No | — | Recargue on-chain: obtenga su dirección de depósito desde la consola o mediante `GET /v1/topup/deposit-address` (MCP `get_deposit_address`); consulte la [guía de recarga para agentes](https://docs.blockvectra.com/en/guides/agent-topup/), use el restablecimiento de cuota si está disponible o espere la asignación del siguiente ciclo. Cuando se conoce el saldo, error.data incluye balance_units (negativo si está sobregirado) y balance_cu. |
| 503 | -32021 | `billing_unavailable` | Datos de facturación no disponibles temporalmente | No | Sí | Respete el encabezado Retry-After (segundos) | No es un problema de saldo; las API keys recién creadas se sincronizan en pocos segundos. Espere según Retry-After y reintente. |
| 200 | -32010 | `node_syncing` | El nodo se está sincronizando; las llamadas no están disponibles temporalmente | No | Sí | Espere unos segundos y reintente | Espere a que termine la sincronización del nodo o verifique GET /v1/status. |
| 200 | -32603 | `upstream_unavailable` | Servicio upstream no disponible | No | Sí | Espere unos segundos y reintente | Reintente con backoff exponencial; consulte GET /v1/status para verificar el estado del nodo. |
| 504 | 504 | `upstream_timeout` | El servicio upstream no respondió dentro del límite de tiempo | No | Sí | Reintente tras una breve pausa | Reintente la solicitud con backoff exponencial. |
| 200 | -32000 | `response_too_large` | Respuesta upstream demasiado grande | No | No | — | Reduzca los parámetros de la consulta (por ejemplo, acorte el rango de bloques en eth_getLogs o solicite traces más pequeños). |
| 200 | -32603 | `internal_error` | Error interno del servicio | No | No | — | Reintente la solicitud; informe de fallos persistentes al soporte con la marca temporal. |
| 200 | 4444 | — | Historial podado no disponible | No | No | — | El bloque está fuera de la ventana de historial conservada por el nodo podado; consulte bloques históricos mediante la Data API. |
| 200 | -32000 | — | historical state ... is not available; old data not available due to pruning... | No | No | — | Consulte bloques dentro de la ventana de estado o utilice la Data API para consultas históricas. |
| 200 | -32002 | — | <node message> | No | Sí | Espere unos segundos y reintente con un lote más pequeño | Reduzca el número de llamadas en el lote y reintente. |
| 200 | -32003 | — | <node message> | No | No | — | Divida el lote en solicitudes más pequeñas para reducir el tamaño de la carga útil de respuesta. |
| 200 | -32601 | — | <node message> | No | No | — | Consulte methods.allow y methods.deny en GET /v1/chains para ver los métodos admitidos. La compatibilidad con el envío de transacciones se determina mediante methods.allow en GET /v1/chains. El envío de transacciones actualmente no está disponible en: HyperEVM. |
| 200 | -32603 | — | <node message> | No | Sí | Espere unos segundos y reintente | Reintente la solicitud; informe de fallos persistentes al soporte con la marca temporal. |
| 200 | -32600 | — | <node message> | No | No | — | Inspeccione las solicitudes individuales en el lote en busca de parámetros no conformes; divida y reintente. |
| 200 | * | — | <node message> | Sí | No | — | El nodo realizó el cómputo y se facturó. Inspeccione el motivo/datos de reversión o los parámetros de llamada; no reintente a ciegas. |
| 408 | 408 | — | La solicitud agotó el tiempo de espera de 35 s entre la recepción completa de los encabezados y la respuesta | Posible | Sí | Espere unos segundos antes de reintentar llamadas de lectura | Las llamadas pueden haber llegado al nodo y haberse facturado. Para lecturas, reintente con backoff. Para escrituras (por ejemplo, eth_sendRawTransaction), compruebe primero el estado de la transacción por su hash. |

### Códigos de cierre de WebSocket

Códigos de cierre de conexión WebSocket y acciones recomendadas para el cliente.

| Código | Motivo | Significado | Reintentable | Tiempo de espera (Retry-After) | Acción del agente |
| --- | --- | --- | --- | --- | --- |
| 1001 | — | Conexión cerrada por inactividad | Sí | Reconéctese según sea necesario | Reconéctese según sea necesario. |
| 1003 | — | Tipo de datos no admitido (por ejemplo, trama binaria en lugar de texto) | No | — | No se reconecte automáticamente; envíe solo tramas de texto UTF-8. |
| 1009 | — | El mensaje supera el límite de tamaño permitido | No | — | No se reconecte automáticamente; divida las solicitudes grandes para no superar 1 MiB. |
| 1012 | — | Reinicio del servicio; la conexión se cerró de forma ordenada | Sí | Reconéctese con backoff y jitter | Reconéctese con backoff y jitter, vuelva a suscribirse y recupere los datos omitidos. |
| 1013 | — | Cadena no disponible; servicio sobrecargado | Sí | Reconéctese con backoff exponencial y full jitter | Reconéctese con backoff exponencial y full jitter, vuelva a suscribirse y recupere los datos omitidos. |
| 4402 | — | Saldo agotado para las suscripciones activas | No | — | No se reconecte automáticamente; recargue on-chain: obtenga su dirección de depósito en la consola o mediante `GET /v1/topup/deposit-address` (MCP `get_deposit_address`); consulte la [guía de recarga para agentes](https://docs.blockvectra.com/en/guides/agent-topup/) o use el restablecimiento de cuota en la consola si es elegible. |
| 4404 | — | API key inválida, deshabilitada o revocada | No | — | No se reconecte automáticamente; verifique o rote la API key en la consola. |
| 4408 | — | El servicio cierra la sesión cuando su cola de notificaciones supera 512 KiB (524.288 bytes) y descarta las notificaciones pendientes; el cliente puede no recibir una trama de cierre (el navegador informa 1006); trate las desconexiones inesperadas como 4408. | Sí | Reconéctese con backoff; reduzca las suscripciones o lea más rápido | Trate una desconexión inesperada sin trama de cierre (el navegador informa 1006) como 4408: reconéctese con backoff, restablezca las suscripciones y recupere los datos perdidos con eth_getLogs; reduzca las suscripciones o lea más rápido. |
| 4429 | — | Tasa de mensajes push superada | Sí | Reconéctese con backoff o reduzca las suscripciones | Reduzca las suscripciones o reconéctese con backoff. |
| 4503 | — | Servicio de facturación no disponible temporalmente | Sí | Reconéctese con backoff exponencial y full jitter | Reconéctese con backoff exponencial y full jitter, y vuelva a suscribirse. |

### Errores de la Data API

Errores devueltos por los endpoints de la Data API de blockchain en /v1/data/{chain}/.

| HTTP | Código | Motivo | Significado | Facturado | Reintentable | Tiempo de espera (Retry-After) | Acción del agente |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 400 | bad_request | — | Parámetro de consulta duplicado, cadena de consulta inválida o solicitud mal formada | No | No | — | Inspeccione los parámetros de consulta; asegúrese de que parámetros como limit aparezcan como máximo una vez y de que los parámetros sean válidos. |
| 409 | not_indexed_yet | — | El número de bloque o ventana solicitada está por encima de as_of_block, o el hash apunta por encima de as_of_block (incluye indexed_through a menos que la cadena no tenga bloques indexados) | No | Sí | Espere unos segundos hasta que indexed_through alcance el bloque | Consulte hasta que el bloque solicitado o to_block sea menor o igual que indexed_through, o espere a que la cadena comience a escribir bloques. |
| 409 | window_too_large | — | La ventana de bloques abarca más de 100,000 bloques y el parámetro clamp no se estableció en true | No | No | — | Reduzca el rango de bloques (from_block a to_block) a <= 100,000 bloques, o envíe clamp=true. |
| 409 | too_many_pools | — | El token coincide con más de 200 pools de liquidez; consulte por dimensión de pool en su lugar | No | No | — | Consulte por la dirección específica del pool en lugar de consultar todos los pools para el token. |
| 409 | span_exceeded | — | El intervalo de fechas solicitado supera el límite máximo de 90 días | No | No | — | Reduzca el rango de fechas entre from_time y to_time a un máximo de 90 días. |
| 422 | no_coverage | — | Capacidad no admitida en esta cadena, o el bloque solicitado es anterior a la ventana de cobertura | No | No | — | Verifique `features` y `coverage.from_block` en GET /v1/data/chains (o `data_features` en el GET /v1/status gratuito) antes de consultar. |
| 503 | unavailable | — | Servicio de datos no disponible temporalmente | No | Sí | Espere unos segundos y reintente con backoff exponencial | Reintente tras una breve pausa con backoff exponencial. |
| 402 | insufficient_balance | — | Saldo de pago o asignación gratuita agotados (cuando se conoce el saldo, error.data incluye balance_units y balance_cu) | No | No | — | Recargue on-chain: obtenga su dirección de depósito en la consola o mediante `GET /v1/topup/deposit-address` (MCP `get_deposit_address`); consulte la [guía de recarga para agentes](https://docs.blockvectra.com/en/guides/agent-topup/) o espere a que se reponga la asignación gratuita. |
| 429 | cost_exceeds_burst | — | Una sola solicitud cuesta más que la capacidad de ráfaga (burst) de la API key | No | No | — | Divida la solicitud en otras más pequeñas; reintentarla tal como se envió nunca tendrá éxito. |
| 503 | gateway_overloaded | — | La capacidad de la Data API no está disponible temporalmente | No | Sí | Retry-After: 1 segundo | Reduzca las solicitudes simultáneas entre las API keys y cadenas de esta cuenta; espere Retry-After antes de reintentar. error.data.reason es null. |

### Errores de las API de consola, cuenta y faucet

Errores devueltos por los endpoints de gestión, aprovisionamiento de API keys, autenticación y faucet en /v1/.

| HTTP | Código | Motivo | Significado | Facturado | Reintentable | Tiempo de espera (Retry-After) | Acción del agente |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 409 | topup_disabled | — | Recarga pausada o sin redes disponibles para recarga en este momento; no se pueden asignar nuevas direcciones, pero las direcciones asignadas existentes permanecen vinculadas a la cuenta | No | No | — | Verifique la disponibilidad de recarga mediante GET /v1/topup/status; reintente más tarde cuando la recarga esté habilitada. |
| 503 | deposit_unavailable | — | No es posible asignar temporalmente una dirección de depósito; reintente según el encabezado Retry-After | No | Sí | Respete el encabezado Retry-After (segundos) y use backoff exponencial | Reintente según el encabezado Retry-After con backoff exponencial. |
| 400 | invalid_request | `invalid_username` | El formato del nombre de usuario no es válido (debe ser alfanumérico o con guiones bajos) | No | No | — | Proporcione un nombre de usuario válido que cumpla con los requisitos de caracteres y longitud. |
| 400 | invalid_request | `expires_at` | La fecha de expiración de la clave no está en el futuro o supera el período máximo de validez permitido | No | No | — | Establezca expires_at en una marca temporal RFC 3339 futura dentro del período de validez permitido (por defecto 365 días), o use expires_in_secs. |
| 400 | invalid_request | `cu_cap` | El parámetro cu_cap está fuera de los límites (debe ser un entero entre 1 y 9007199254740991) | No | No | — | Ajuste cu_cap para que sea un número entero entre 1 y 9007199254740991 u omítalo para CU ilimitadas. |
| 400 | siwe_invalid | `expired` | El mensaje de Sign-In with Ethereum (SIWE) ha expirado o el nonce ya se utilizó | No | Sí | Obtenga un nuevo desafío de inmediato y fírmelo | Solicite un nuevo desafío en /v1/auth/siwe/challenge y firme la declaración recién emitida. |
| 400 | siwe_invalid | `chain_mismatch` | El chainId del mensaje SIWE no coincide con la configuración del servidor | No | No | — | Use el chainId devuelto por /v1/auth/siwe/challenge al construir el mensaje SIWE. |
| 400 | siwe_invalid | `domain_mismatch` | El dominio del mensaje SIWE no coincide con el host del servidor | No | No | — | Asegúrese de que el dominio y el uri coincidan con el host del servidor devuelto en el desafío. |
| 400 | siwe_invalid | `signature` | Falló la verificación criptográfica de la firma SIWE | No | No | — | Verifique que el mensaje haya sido firmado por la clave privada correspondiente a la dirección especificada. |
| 409 | key_limit_reached | `active_keys` | Se alcanzó el número máximo de API keys activas (no revocadas) de la cuenta | No | No | — | Revoque una API key existente que no utilice antes de crear una nueva. |
| 409 | no_reset_available | `nothing_to_reset` | El saldo ya es igual o superior al objetivo de restablecimiento; se conserva la oportunidad de restablecer | No | No | — | No hace falta restablecer ahora; utilice la oportunidad cuando se agote el saldo. |
| 429 | rate_limited | `daily_creations` | Se alcanzó el límite de creación de API keys en 24 horas de la cuenta | No | Sí | Respete el encabezado Retry-After (segundos) | Rote las API keys existentes en lugar de crear nuevas, o espere a que se restablezca la ventana de 24 horas. |
| 429 | signup_rate_limited | `per_ip` | Se alcanzó el límite de registro para la subred IP del cliente | No | Sí | Respete el encabezado Retry-After (segundos) | Espere el intervalo de Retry-After antes de crear una cuenta nueva desde esta red. |
| 429 | signup_rate_limited | `global` | Se alcanzó el límite global de registro de nuevos usuarios en todas las fuentes | No | Sí | Respete el encabezado Retry-After (segundos) | Espere el intervalo de Retry-After antes de reintentar la creación de la cuenta. |
| 400 | oauth_invalid | — | Parámetro OAuth inválido o estado del callback desconocido, expirado o ya utilizado | No | Sí | — | Inicie un nuevo flujo de inicio de sesión OAuth desde /v1/auth/{provider}/start. |
| 400 | login_code_invalid | — | Código de inicio de sesión desconocido, expirado, ya utilizado o con un verificador PKCE que no coincide | No | No | — | Reinicie el inicio de sesión para obtener un nuevo código. |
| 401 | unauthenticated | — | Sesión ausente o token de sesión inválido, expirado o revocado; en la Top-up API (/v1/topup/*), también ocurre cuando Authorization contiene un token inválido o que no es Bearer en lugar de x-api-key | No | No | — | Inicie sesión nuevamente para obtener un nuevo token de sesión Bearer; en la Top-up API, envíe la API key mediante x-api-key en lugar de Authorization. |
| 403 | user_disabled | — | La cuenta de usuario ha sido suspendida o deshabilitada | No | No | — | Contacte con contact@blockvectra.com para obtener asistencia con su cuenta. |
| 404 | provider_disabled | — | Proveedor OAuth reconocido pero deshabilitado actualmente | No | No | — | Use SIWE u otro proveedor de autenticación compatible. |
| 409 | identity_in_use | — | La identidad de autenticación ya está vinculada a otra cuenta | No | No | — | Desvincule la identidad de la cuenta anterior o utilice otra identidad. |
| 409 | identity_limit_reached | — | Se alcanzó el máximo de identidades vinculadas (5) de esta cuenta | No | No | — | Desvincule una identidad existente antes de vincular una nueva. |
| 409 | last_identity | — | No se puede eliminar la única identidad vinculada a la cuenta | No | No | — | Vincule otro método de autenticación antes de eliminar esta identidad. |
| 409 | key_not_active | — | Se intentó rotar una API key deshabilitada, revocada o expirada | No | No | — | Cree una nueva API key o rote una API key activa. |
| 409 | no_reset_available | — | No quedan oportunidades de restablecimiento de cuota en esta cuenta | No | No | — | Recargue on-chain: obtenga su dirección de depósito en la consola o mediante `GET /v1/topup/deposit-address` (MCP `get_deposit_address`); consulte la [guía de recarga para agentes](https://docs.blockvectra.com/en/guides/agent-topup/) o espere al siguiente ciclo de promoción. |
| 413 | payload_too_large | — | El cuerpo de la solicitud supera el límite de 64 KiB | No | No | — | Reduzca el cuerpo de la solicitud por debajo de 64 KiB. |
| 503 | signup_paused | — | El registro global de nuevos usuarios está pausado temporalmente; los inicios de sesión existentes no se ven afectados | No | Sí | Reintente el registro más tarde | El registro de nuevos usuarios está pausado temporalmente; compruebe el estado y reintente más tarde. |
| 503 | usage_unavailable | — | Las estadísticas de uso no están disponibles temporalmente | No | Sí | Espere unos segundos y reintente | Solo afecta al punto de enlace /usage; los demás funcionan normalmente. Reintente en breve. |
| 500 | internal | — | Error inesperado del servidor | No | Sí | Reintente tras una breve pausa | Reintente la solicitud con backoff exponencial. |
| 400 | invalid_address | `invalid_address` | El formato o la suma de comprobación (checksum) de la dirección del destinatario no son válidos | No | No | — | Use 0x seguido de 40 caracteres hexadecimales, en minúsculas o con checksum EIP-55; revise data.field (/address). |
| 503 | faucet_empty | `faucet_empty` | El faucet no dispone de fondos suficientes para la reclamación y la tarifa de transacción | No | Sí | Respete el encabezado Retry-After (segundos) | Espere según Retry-After antes de reintentar; no asuma que se ha enviado ETH de prueba sin una respuesta de aceptación. |
| 503 | service_unavailable | `service_unavailable` | El procesamiento de reclamaciones del faucet no está disponible temporalmente o una reclamación anterior aún no tiene recibo | No | Sí | Respete el encabezado Retry-After (segundos) | Espere según Retry-After antes de reintentar; no asuma que se ha enviado ETH de prueba sin una respuesta de aceptación. |

### Errores de la Push API

Errores de gestión de suscripciones de Webhook e historial de eventos en /v1/push/.

| HTTP | Código | Motivo | Significado | Facturado | Reintentable | Tiempo de espera (Retry-After) | Acción del agente |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 400 | invalid_request | — | Campos de solicitud, direcciones, paginación o rango de bloques no válidos. | No | No | — | Inspeccione data.field y data.invalid; corrija la solicitud. |
| 401 | missing_api_key | — | Encabezado x-api-key ausente. | No | No | — | Proporcione su API key en el encabezado x-api-key. |
| 401 | invalid_api_key | — | API key desconocida, deshabilitada o revocada. | No | No | — | Utilice una API key activa de su cuenta. |
| 402 | insufficient_balance | — | Saldo o asignación gratuita agotados para el historial de eventos. | No | No | — | Inspeccione data.reason (balance_exhausted o free_grant_exhausted) y data.balance_units / data.balance_cu cuando estén presentes; recargue mediante data.topup_url o data.deposit_address_url. |
| 403 | key_cap_exhausted | — | Límite de CU de la API key agotado para el historial de eventos. | No | No | — | Inspeccione data.cu_cap y cree una nueva API key en la consola. |
| 403 | key_expired | — | La API key ha expirado. | No | No | — | Utilice una API key no expirada de su cuenta. |
| 404 | not_found | — | Ruta, método o suscripción no encontrados. | No | No | — | Verifique la ruta, el método y la propiedad de la suscripción. |
| 409 | limit_reached | — | Límite de suscripciones o pares de direcciones de la cuenta alcanzado. | No | No | — | Inspeccione data.limit y data.max; reduzca suscripciones o direcciones. |
| 413 | request_too_large | — | El cuerpo de la solicitud supera el límite de la ruta. | No | No | — | Divida el lote de direcciones o reduzca el tamaño del cuerpo. |
| 422 | chain_not_available | — | Cadena no disponible para Push o ausente en la suscripción. | No | No | — | Consulte GET /v1/push/chains y las cadenas de la suscripción. |
| 422 | chains_required | — | Se requiere al menos una cadena. | No | No | — | Proporcione un objeto chains no vacío; use el estado offline para dejar de escuchar. |
| 422 | confirmations_out_of_range | — | Profundidad de confirmaciones fuera del rango permitido para la cadena. | No | No | — | Elija un valor de confirmations entre data.min y data.max. |
| 422 | destination_not_allowed | — | La URL de destino no está permitida. | No | No | — | Inspeccione data.rule; use un nombre de host HTTPS en el puerto 443 sin información de usuario ni fragmento. |
| 422 | block_out_of_range | — | Rango de bloques fuera de la cobertura disponible de retransmisión o historial. | No | No | — | Use data.min_block y data.max_block para ajustar el rango. |
| 429 | cost_exceeds_burst | — | El costo de la solicitud de historial supera la capacidad de ráfaga (burst) de la API key. | No | No | — | Inspeccione data.reason (request_exceeds_burst) y data.max; aumente la capacidad de ráfaga antes de reintentar. Reintentar sin cambios no servirá de nada. |
| 429 | rate_limited | — | Límite de tasa de consultas de gestión o historial alcanzado. | No | Sí | Espere los segundos indicados en Retry-After. | Para el historial, inspeccione data.reason (key_rate_limit o free_plan_call_limit); espere los segundos indicados en Retry-After y reduzca la frecuencia o concurrencia de solicitudes. |
| 500 | internal_error | — | Error inesperado del servicio. | No | No | — | Guarde x-request-id y póngase en contacto con el soporte técnico. |
| 503 | auth_unavailable | — | Validación de la API key no disponible temporalmente. | No | Sí | Espere los segundos indicados en Retry-After. | Espere los segundos indicados en Retry-After antes de reintentar. |
| 503 | billing_unavailable | — | Estado de facturación del historial no disponible temporalmente. | No | Sí | Espere los segundos indicados en Retry-After. | Espere los segundos indicados en Retry-After antes de reintentar. |
| 503 | upstream_unavailable | — | Servicio Push temporalmente inaccesible. | No | Sí | Espere los segundos indicados en Retry-After. | Espere los segundos indicados en Retry-After antes de reintentar. |
| 503 | service_unavailable | — | Servicio Push o capacidad de direcciones no disponible temporalmente. | No | Sí | Espere los segundos indicados en Retry-After. | Espere los segundos indicados en Retry-After antes de reintentar. |

Para errores de suscripción o retransmisión de Webhooks, siga la [guía de recuperación de entregas Push](https://docs.blockvectra.com/en/guides/webhook-push/#delivery-retries-and-replay). La integración del receptor comienza con la [verificación de firma en el cuerpo sin procesar](https://docs.blockvectra.com/en/guides/webhook-push/#verify-signatures); el [ejemplo de pagos con stablecoins](https://docs.blockvectra.com/en/guides/stablecoin-payments/#receive-payments-with-webhooks) añade deduplicación de eventos, verificación de recibos, recuperación de brechas y conciliación de reorganizaciones (reorgs). Consulte las [reglas de facturación](https://docs.blockvectra.com/en/guides/billing-rules/#webhook-push-billing) para la medición y la [reconexión de WebSocket](https://docs.blockvectra.com/en/guides/websocket-subscriptions/#reconnection-and-exponential-backoff) para suscripciones basadas en conexión.

Para `logs_range_too_large`, consulte los [parámetros del método eth\_getLogs](https://docs.blockvectra.com/en/api/json-rpc/methods/eth_getLogs/) y siga la [guía de límites de rango de bloques y consultas por fragmentos](https://docs.blockvectra.com/en/guides/getlogs-block-range/).

Para solicitudes de faucet en Robinhood Chain, consulte la [guía de faucet de testnet](https://docs.blockvectra.com/en/guides/robinhood-testnet-faucet/) para ver los criterios de elegibilidad y el tratamiento de códigos de error compartidos.