Limity a chyby

How many requests your app can make, what an error response looks like and how to tell a failed request from a successful one.

Rate limits

Limits apply per access token and app. Every request also counts towards the per-minute limit, including order and backtest requests.

Bucket	Endpoints	Limit
Orders	`POST /hopper/{id}/order`, `POST /hopper/{id}/position/sell` and `POST /hopper/{id}/position/sell/{position_id}`	1 request every 8 seconds
Backtests	`GET` and `POST /hopper/{id}/backtest`, `GET /hopper/{id}/backtest/{start}/{limit}`	1 request every 2 seconds
Everything else	All other endpoints	30 requests per minute, at most 1 per second

When you go over a limit the API answers with status 429 and a message that says how many seconds to wait, for example Rate limit reached, please try again after 12 seconds. Wait that long before you try again, and spread bulk work over time instead of sending it in bursts.

Responses

A successful request returns JSON with the result under data. A failed request returns JSON with "error": 1, a status and a message:

{
    "status": 403,
    "code": 0,
    "error": 1,
    "message": "Unauthorized access.",
    "ip_address": "203.0.113.7"
}

Errors from the API gateway itself, such as a missing token or an unknown path, have no code or ip_address:

{
    "status": 400,
    "error": 1,
    "message": "Missing required request parameters: [access-token]"
}

Check the error field, not the HTTP status code. Errors from the API can arrive with HTTP status 200 and gateway errors with HTTP status 405. The real status is the status field in the body, which can be a number or a string.

const response = await fetch(url, { headers: { 'access-token': token } });
const body = await response.json();

if (body.error) {
  // body.status holds the real status code, whatever response.status says
  throw new Error(`Cryptohopper API ${body.status}: ${body.message}`);
}
const data = body.data;

Common errors

Status	Message	What it means
400	Missing required request parameters: [access-token]	The request has no `access-token` header. An `Authorization: Bearer` header is not accepted.
400	Missing Authentication Token	The path or method does not exist. Check it against the API reference.
403	Unauthorized access.	The access token is invalid or has been revoked.
403	Access token expired	The access token has expired. Ask the user to authorize your app again.
403	You do not have the correct permissions for this request.	The token lacks a scope the endpoint needs. The message lists the permissions needed and the ones the token has.
403	Invalid IP address.	Your app has an IP whitelist and the request came from another address.
402	This app is currently unavailable because the developer does not have an active subscription.	Apps only work while their developer has an active Cryptohopper subscription. `code` is 4030.
429	Rate limit reached, please try again after N seconds.	Too many requests. Wait the number of seconds in the message.

Scopes per endpoint are listed in the API reference. How users authorize your app is on the Authentication page.