Rate Limits

The VoiceLayer API allows user an authenticated user to make a certain number of API calls per hour. The REST API and GraphQL API have separate rate limits. and are discussed in their own sections.

Sending/receiving messages, websocket connections and push notifications do not count towards these limits.

REST API

The REST API allows an authenticated user to make up to 2000 API calls per hour. Each request will increment the number of requests used and the current values are returned as the following response headers:

x-rate-limit-limit: 2000
x-rate-limit-remaining: 1999
x-rate-limit-reset: 1551185407

Where:

  • x-rate-limit-limit - total limit for the user
  • x-rate-limit-remaining - remaining requests allowed for the time period
  • x-rate-limit-reset - timestamp when the limit will be reset

If the rate limit is exceeded, a 429 status code will be returned and the request will not be successful.

GraphQL API

Rate limits

Since a single GraphQL query can return the data of many API calls, the cost for each query is calculated in a different way. Each query is assigned a cost, and that cost is deducted from the rate limit. The cost is determined by the number of pages being requested. The total cost permitted per hour 2000.

Consider the following query:

viewer {
  name
  admin
  channels(first: 20) {
    edges {
      node {
        name
        channelUsers(first: 30) {
          edges {
            node {
              admin
              user {
                channels(first:40) {
                  edges {
                    node {
                      id
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

The cost of this query is:

  • 1 = 1 for the viewer
  • 1 * 20 = 20 for the 20 channels belonging to viewer
  • 1 * 20 * 30 = 600 for the 30 channelUsers belonging to each channel
  • Total = 621

    We normalize this figure by dividing by 100 and round up, so the total cost for this query is 7.

Node limit

VoiceLayer also ensures that an individual request is not too expensive, each node is associated a cost of 1, with pagination nodes being multiplied by the count of the child nodes.

Using the above query as an example, the potential maximum node count is:

  • viewer - 1
  • admin - 1
  • channels - 0
  • edges - (1 * 20) = 20
  • node - (1 * 20) = 20
  • name - (1 * 20) = 20
  • channelUsers - 0
  • edges - (1 * 20 * 30) = 600
  • node - (1 * 20 * 30) = 600
  • admin - (1 * 20 * 30) = 600
  • user - (1 * 20 * 30) = 600
  • channels - 0
  • edges - (1 * 20 * 30 * 40) = 24000
  • node - (1 * 20 * 30 * 40) = 24000
  • id - (1 * 20 * 30 * 40) = 24000

Total = (1 * 2) + (20 * 3) + (600 * 4) + (24000 * 3) = 74462

The maximum permitted node count for a query is 100000 - queries above this will be rejected.

Finding our current rate limit:

The rate limit can be determined with the following query:

rateLimit {
  cost
  limit
  nodeCount
  remaining
  resetAt
}

How to avoid hitting rate limits

During typical usage, it is unlikely that these rate limits will be reached. However there are some things you can do in your application to prevent it.

Caching responses and only fetching the data required is a good way to avoid hitting the rate limits. For example if you are targeting a specific user, use the search API instead of fetching all the users and paging through until you find the desired user. After fetching the user, use the user:update to listen for changes on the user.

To request higher rate limits, please contact support@voicelayer.io