Error reference
This page lists the errors returned by the Cryptohopper Market Data MCP and describes the cause and recommended handling for each.
For a task-oriented troubleshooting guide, see troubleshoot common MCP errors.
Error format
Errors are returned to the MCP client in the standard MCP error envelope. The fields:
| Field | Type | Description |
|---|---|---|
| code | string | A stable, uppercase identifier (e.g. QUOTA_EXCEEDED). |
| message | string | A human-readable description. |
| details | object | Optional structured context. |
The code is the stable contract. Clients should branch on code, not on the text of message.
Authentication errors
UNAUTHORIZED
The API key is missing, malformed, expired, or revoked.
Common causes:
- No Authorization header in the request.
- Malformed bearer token (whitespace, copy-paste artefacts).
- Key has been revoked in the Cryptohopper account interface.
- Key was generated for a different product and is not valid for the MCP.
Handling: regenerate the key from the Cryptohopper account interface and reconfigure the client. See API key security best practices and how to get a Cryptohopper MCP API key.
FORBIDDEN
The request is authenticated but the account does not have permission to perform the requested action.
Common causes:
- Account is suspended or flagged.
- The endpoint has been restricted for the account.
Handling: contact Cryptohopper support. Regenerating the key will not resolve this error.
Quota and rate-limit errors
QUOTA_EXCEEDED
The account has reached its weekly call limit.
Handling: wait for the next reset (Friday), upgrade the subscription tier, or audit call patterns to reduce usage. The details.reset_at field contains the timestamp of the next reset.
See rate limits explained and subscription tiers.
RATE_LIMIT_EXCEEDED
The account has exceeded the short-interval rate limit.
Handling: retry after a brief delay. Well-behaved clients back off exponentially; an initial retry after 500ms is typically sufficient. If the error recurs, add a small delay between sequential calls in your workflow.
HISTORY_LIMIT_EXCEEDED
A candle request specified a lookback greater than the active tier's maximum history.
Handling: reduce the lookback, or upgrade to a tier with deeper history. See subscription tiers.
Tier and access errors
EXCHANGE_NOT_SUPPORTED
The requested exchange is not available to the active tier, or is not supported by the MCP at all.
Handling: confirm the exchange is in the tier's allow list in supported exchanges. If the exchange is listed for a higher tier, upgrade. If it is not listed at all, the exchange is not supported.
PAIR_NOT_FOUND
The requested pair does not exist on the specified exchange, or the pair symbol is malformed.
Handling: verify the pair symbol using the list-pairs tool. Pair symbols use the BASE/QUOTE format (e.g. BTC/USDT).
TIMEFRAME_NOT_SUPPORTED
The requested candle timeframe (interval) is not supported for this exchange or pair.
Handling: use a supported timeframe. See candle tool reference.
Request errors
INVALID_PARAMETER
One or more tool arguments failed validation.
Common causes:
- Lookback less than 1 or above the tier maximum.
- Non-string values where strings are required.
- Malformed exchange or pair identifiers.
Handling: the details object contains the offending parameter. Correct and retry.
MISSING_PARAMETER
A required argument was not provided.
Handling: the details object names the missing parameter. Correct and retry.
Upstream errors
EXCHANGE_UNAVAILABLE
The underlying exchange API is not responding or is returning errors. This is typically transient.
Handling: retry after a short delay. If the error persists across multiple exchanges, it may indicate an MCP-side incident — check the Cryptohopper status page.
DATA_UNAVAILABLE
The requested data exists conceptually but is temporarily unavailable (for example, a candle series that has not yet been populated).
Handling: retry after a delay. For long-running outages, pick a different exchange or a different pair.
Server errors
INTERNAL_ERROR
An unexpected error occurred inside the MCP server.
Handling: retry once. If the error persists, report it through Cryptohopper support with the details.trace_id if present.
SERVICE_UNAVAILABLE
The MCP service is temporarily unable to handle requests. Usually during maintenance or under unusual load.
Handling: retry after a delay. Check the Cryptohopper status page for ongoing incidents.
Quick-reference table
| Code | Category | Retry? | Fix |
|---|---|---|---|
| UNAUTHORIZED | Auth | No | Regenerate key |
| FORBIDDEN | Auth | No | Contact support |
| QUOTA_EXCEEDED | Quota | At reset | Upgrade tier or reduce usage |
| RATE_LIMIT_EXCEEDED | Quota | After delay | Throttle client |
| HISTORY_LIMIT_EXCEEDED | Tier | No | Reduce lookback / upgrade tier |
| EXCHANGE_NOT_SUPPORTED | Tier | No | Check tier allow list |
| PAIR_NOT_FOUND | Request | No | Verify pair symbol |
| TIMEFRAME_NOT_SUPPORTED | Request | No | Use supported timeframe |
| INVALID_PARAMETER | Request | No | Fix parameter |
| MISSING_PARAMETER | Request | No | Add parameter |
| EXCHANGE_UNAVAILABLE | Upstream | Yes | Brief retry |
| DATA_UNAVAILABLE | Upstream | Yes | Delay then retry |
| INTERNAL_ERROR | Server | Once | Report if persistent |
| SERVICE_UNAVAILABLE | Server | Yes | Delay then retry |