Home / Basics / Highnote API

API Rate Limiting

Rate Limits

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 and Complexity.

Rate limiting is based on which type you hit first. Each type has a specific rate limit for each Auth/API type:

Request 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

If your request is rate limited, the Highnote API will return a 429 TOO MANY REQUESTS status code.

If you exceed the API rate limit, the cost field will not be present in your API response. The Highnote GraphQL API uses a retryAfter field to show how long to wait before retrying, instead of giving the query cost.

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

Rate Limited Response Example
{
  "errors": [
    {
      "message": "Usage limit exceeded. More than x request complexity points used in y seconds. See https://highnote.com/docs/basics/graphql-api/api-rate-limiting for details on how to handle API rate limits."
    }
  ],
  "extensions": {
    "rateLimit": {
      "limit": 5000,
      "remaining": 50,
      "retryAfter": 10
    },
    "requestId": "REQUEST_ID"
  }
}

Tips to Avoid Hitting Rate Limits

Avoid Polling

Avoid polling the API for asynchronous updates by registering a webhook target to receive notification events. To learn more, see Notifications.

Use Pagination

When querying for listed data, use pagination to limit the number of requested items.

Implement Exponential Backoff

Implement retries with exponential backoff when an API request receives a 429 TOO MANY REQUESTS response. Use the following resources to implement exponential backoff:

Provide Feedback

Was this content helpful?