Skip to main content

API Rate Limiting

Rate limits​

test vs. live environments

By default the Test environment has 50% of the rate limit of the Live environment.

To maintain optimal performance, an API rate limit limits the number of requests a client can make within a specific time frame. The Highnote platform has different rate limit types:

  • Request count
  • Complexity

Rate limiting is based on which type you hit first. And each rate limit type is different for each Auth/API type.

Request count rate limits​

Auth/API TypeLimitNote
API key200 requests per 10 secondsAggregate limit across all API keys assigned to an org
Client token20 requests per 10 seconds per user/subject
REST API200 requests per 10 seconds

Complexity rate limits​

Auth/API TypeLimitNote
API key5,000 complexity per 10 secondsAggregate limit across all API keys assigned to an org
Client token5,000 complexity per 10 seconds per user/subject
REST APIN/A

For more information on calculating request complexity, see Request Complexity.

Rate limited responses​

When an API request is rate limited, Highnote API returns a 429 TOO MANY REQUESTS status code.

If you exceed the API rate limit, the cost field is not returned in your API response. Instead, the Highnote API uses a retryAfter field to show how long to wait before retrying.

The following example represents a response of a rate-limited API request:

When request is rate limited​

The following example represents a response of a request that is rate-limited:

{
  "data": {},
  "errors": [
    {
      "message": "Usage limit exceeded. More than x request points used in y seconds. See https://highnote.com/docs/developers/api/error-handling#rate-limit-errors for details on how to handle API rate limits."
    }
  ],
  "extensions": {
    "requestId": "4378192a-3529-928c-9894-5f815edd4f07",
    "rateLimit": {
      "asOf": "2024-03-15T18:29:36.090Z",
      "count": {
        "cost": 1,
        "remaining": 0,
        "limit": 200
      },
      "complexity": {
        "remaining": 0,
        "limit": 2500
      },
      "remaining": "0",
      "limit": 2500
    }
  }
}

When request is not rate limited​

The following example represents a response of a request that is not rate-limited:

{
  "data": {},
  "errors": {},
  "extensions": {
    "requestId": "4378192a-3529-928c-9894-5f815edd4f07",
    "rateLimit": {
      "asOf": "2024-03-15T18:29:36.090Z",
      "count": {
        "cost": 1,
        "remaining": 199,
        "limit": 200
      },
      "complexity": {
        "cost": 10,
        "remaining": 2490,
        "limit": 2500
      },
      "cost": "10",
      "remaining": "2490",
      "limit": 2500
    }
  }
}

Best practices​

Refer to the following best practices to avoid hitting rate limits: