Rate limits

Learn about API rate limits and how to work with them.

HL Connect limits how many requests you can send. This keeps the API stable for every partner. The numbers below are maximums, so do not send more traffic than you need. If you send more, you get 429 Too Many Requests instead of your data.

---

Rate limits

Limits are counted in requests per second, per vendor. All tokens of one vendor share the same budget. A second or a third token does not give you more requests.

Resource	Limit
GET /assets/list	20 requests per second
POST /assets/search	20 requests per second
POST /assets/history	10 requests per second
GET /purchase/info	50 requests per second
POST /purchase/register	50 requests per second
POST /purchase/validate-purchase-before-payment	50 requests per second
GET /purchase/download-url	50 requests per second
GET /purchase/view-url	50 requests per second
DELETE /purchase/cancel	50 requests per second
GET /assets/categories	20 requests per second

Rate-limited responses

Every response tells you how much budget is left. You do not need to wait for a 429 to see that you are close to the limit.

Header	Meaning
X-Rate-Limit-Limit	The size of your budget for this endpoint.
X-Rate-Limit-Remaining	How many requests you can still send right now.
X-Rate-Limit-Reset	Seconds until your budget is full again. 0 means less than one second.

A request that hits the limit returns 429 with the same headers:

HTTP/1.1 429 Too Many Requests
X-Rate-Limit-Limit: 20
X-Rate-Limit-Remaining: 0
X-Rate-Limit-Reset: 1
{
    "name": "Too Many Requests",
    "message": "Rate limit exceeded.",
    "code": 0,
    "status": 429
}

A 429 means we did not process the request. Nothing was created and nothing was changed. You can safely send the same request again later.

Common causes

• Many requests sent close together. This is usually a catalog download or a data migration. Slow the requests down on your side. See Handle limiting.
• Many small pages instead of a few large ones. Most of the cost of a request does not depend on the page size. Reading the catalog one asset at a time spends your budget much faster than reading it in pages of 100.
• A loop with a bad parameter. A request that fails still uses one slot of your budget. A common case is an empty value, for example last_id=. It returns 400 Bad Request, so the loop spends the whole budget and gets no data.

Handle limiting

Watch X-Rate-Limit-Remaining and slow down before you hit the limit. When you get a 429, wait the number of seconds from X-Rate-Limit-Reset, then try again. Do not retry at once in a loop. You will only get another 429.

Wait longer after each failed retry (exponential backoff) and add a small random delay. Then several of your workers do not retry at the same time. For a catalog download, one request at a time is enough. Reading pages one after another with last_id stays well inside the limit.