Referencia de errores
Esta página lista los errores devueltos por el MCP de Datos de Mercado de Cryptohopper y describe la causa y el manejo recomendado para cada uno.
Para una guía de resolución de problemas orientada a tareas, consulta cómo solucionar errores comunes del MCP.
Formato de error
Los errores se devuelven al cliente MCP en el sobre de error estándar del MCP. Los campos:
| Campo | Tipo | Descripción |
|---|---|---|
| code | string | Un identificador estable en mayúsculas (ej. QUOTA_EXCEEDED). |
| message | string | Una descripción legible para humanos. |
| details | object | Contexto estructurado opcional. |
El code es el contrato estable. Los clientes deben ramificar según el code, no según el texto del message.
Errores de autenticación
UNAUTHORIZED
La clave api falta, está mal formada, expirada o revocada.
Causas comunes:
- No hay encabezado Authorization en la solicitud.
- Token bearer mal formado (espacios en blanco, artefactos de copiar-pegar).
- La clave ha sido revocada en la interfaz de cuenta de Cryptohopper.
- La clave fue generada para un producto diferente y no es válida para el MCP.
Manejo: regenera la clave desde la interfaz de cuenta de Cryptohopper y reconfigura el cliente. Consulta las mejores prácticas de seguridad de claves api y cómo obtener una clave api del MCP de Cryptohopper.
FORBIDDEN
La solicitud está autenticada pero la cuenta no tiene permiso para realizar la acción solicitada.
Causas comunes:
- La cuenta está suspendida o marcada.
- El endpoint ha sido restringido para la cuenta.
Manejo: contacta al soporte de Cryptohopper. Regenerar la clave no resolverá este error.
Errores de cuota y límite de tasa
QUOTA_EXCEEDED
La cuenta ha alcanzado su límite de llamadas semanales.
Manejo: espera el próximo reinicio (viernes), actualiza el nivel de suscripción o audita los patrones de llamadas para reducir el uso. El campo details.reset_at contiene la marca de tiempo del próximo reinicio.
Consulta los límites de tasa explicados y niveles de suscripción.
RATE_LIMIT_EXCEEDED
La cuenta ha excedido el límite de tasa de intervalo corto.
Manejo: reintenta después de un breve retraso. Los clientes bien comportados retroceden exponencialmente; un reintento inicial después de 500ms es típicamente suficiente. Si el error se repite, agrega un pequeño retraso entre llamadas secuenciales en tu flujo de trabajo.
HISTORY_LIMIT_EXCEEDED
Una solicitud de velas especificó un lookback mayor que el historial máximo del nivel activo.
Manejo: reduce el lookback, o actualiza a un nivel con historial más profundo. Consulta los niveles de suscripción.
Errores de nivel y acceso
EXCHANGE_NOT_SUPPORTED
El exchange solicitado no está disponible para el nivel activo, o no es compatible con el MCP en absoluto.
Manejo: confirma que el exchange está en la lista de permitidos del nivel en exchanges compatibles. Si el exchange está listado para un nivel superior, actualiza. Si no está listado en absoluto, el exchange no es compatible.
PAIR_NOT_FOUND
El par solicitado no existe en el exchange especificado, o el símbolo del par está mal formado.
Manejo: verifica el símbolo del par usando la herramienta list-pairs. Los símbolos de pares usan el formato BASE/QUOTE (ej. BTC/USDT).
TIMEFRAME_NOT_SUPPORTED
El intervalo de tiempo de velas (intervalo) solicitado no es compatible para este exchange o par.
Manejo: usa un intervalo de tiempo compatible. Consulta la referencia de la herramienta candle.
Errores de solicitud
INVALID_PARAMETER
Uno o más argumentos de la herramienta no pasaron la validación.
Causas comunes:
- Lookback menor a 1 o superior al máximo del nivel.
- Valores no-string donde se requieren strings.
- Identificadores de exchange o par mal formados.
Manejo: el objeto details contiene el parámetro problemático. Corrige y reintenta.
MISSING_PARAMETER
No se proporcionó un argumento requerido.
Manejo: el objeto details nombra el parámetro faltante. Corrige y reintenta.
Errores upstream
EXCHANGE_UNAVAILABLE
La api del exchange subyacente no está respondiendo o está devolviendo errores. Esto es típicamente transitorio.
Manejo: reintenta después de un corto retraso. Si el error persiste en múltiples exchanges, puede indicar un incidente del lado del MCP — verifica la página de estatus de Cryptohopper.
DATA_UNAVAILABLE
Los datos solicitados existen conceptualmente pero están temporalmente no disponibles (por ejemplo, una serie de velas que aún no ha sido poblada).
Manejo: reintenta después de un retraso. Para interrupciones prolongadas, elige un exchange diferente o un par diferente.
Errores del servidor
INTERNAL_ERROR
Ocurrió un error inesperado dentro del servidor MCP.
Manejo: reintenta una vez. Si el error persiste, repórtalo a través del soporte de Cryptohopper con el details.trace_id si está presente.
SERVICE_UNAVAILABLE
El servicio MCP está temporalmente incapaz de manejar solicitudes. Usualmente durante mantenimiento o bajo carga inusual.
Manejo: reintenta después de un retraso. Verifica la página de estatus de Cryptohopper para incidentes en curso.
Tabla de referencia rápida
| Code | Categoría | ¿Reintentar? | Solución |
|---|---|---|---|
| UNAUTHORIZED | Auth | No | Regenerar clave |
| FORBIDDEN | Auth | No | Contactar soporte |
| QUOTA_EXCEEDED | Quota | Al reinicio | Actualizar nivel o reducir uso |
| RATE_LIMIT_EXCEEDED | Quota | Después de retraso | Limitar cliente |
| HISTORY_LIMIT_EXCEEDED | Tier | No | Reducir lookback / actualizar nivel |
| EXCHANGE_NOT_SUPPORTED | Tier | No | Verificar lista de permitidos del nivel |
| PAIR_NOT_FOUND | Request | No | Verificar símbolo del par |
| TIMEFRAME_NOT_SUPPORTED | Request | No | Usar intervalo de tiempo compatible |
| INVALID_PARAMETER | Request | No | Corregir parámetro |
| MISSING_PARAMETER | Request | No | Agregar parámetro |
| EXCHANGE_UNAVAILABLE | Upstream | Sí | Breve reintento |
| DATA_UNAVAILABLE | Upstream | Sí | Retraso y luego reintentar |
| INTERNAL_ERROR | Server | Una vez | Reportar si persiste |
| SERVICE_UNAVAILABLE | Server | Sí | Retraso y luego reintentar |