Usage limits

In order to protect EventsAir servers from excessive or malicious calls the EventsAir GraphQL API includes some limits.

caution

These limits are subject to change as we observe how the GraphQL API is used and balance usage with the performance of the EventsAir platform.

Rate limit

Limit

A maximum of 750 HTTP requests over a 5-minute window are allowed.

If this rate is exceeded, a HTTP 429 Too Many Requests response status code will be returned.

GraphQL query depth limit

GraphQL queries can have multiple levels of nesting, for example, this query has 5 levels of nesting:

query ExampleQuery($eventId: ID!) {
  event(id: $eventId) {
    registrationTypes {
      registrations {
        contact {
          customFields {
            # ...
          }
        }
      }
    }
  }
}

Limit

A single query can have a maximum depth of 7.

Executing a query with more than 7 levels of nesting, will result in an error:

HTTP/1.1 500

{
  "data": {},
  "errors": [
    {
      "message": "Query exceeds max depth",
      "extensions": {
        "code": "INTERNAL_SERVER_ERROR"
      }
    }
  ]
}

GraphQL operation limits

Operations using the EventsAir GraphQL API are allocated a cost which is measured in points.

Limits

A single operation is limited to 5,000 points.
A limit of 1,000,000 points for all operations applies over a 1-hour sliding window.

Calculating cost points

Cost points for an operation are calculated as follows:

• Most mutation operations have a cost of 2 points. Some exceptions may apply for specific mutations.

• Most GraphQL objects have a cost of 1 point. Some exceptions may apply for specific objects.

• The cost of a GraphQL object is the greater of the object's own cost and the cost of all its children.

• For fields that return arrays and include a limit argument, the cost is calculated by multiplying the cost of the object by the limit.

• The cost of sibling array fields in an object are added together. For example, the highlighted lines in the following query each have a cost of 20 points. The resulting cost for the event object is 40 points.

  query ExampleQuery($eventId: ID!) {
    event(id: $eventId) {
      customFields(limit: 20) {
        name
      }
      registrationTypes(limit: 20) {
        id
      }
    }
  }

• The cost of a hierarchy of array fields are multiplied together. For example, the highlighted lines in the following query each have a cost of 20 points, however, since registrations are nested within registrationTypes, the resulting cost of the event object is 20 x 20 = 400 points.

  query ExampleQuery($eventId: ID!) {
    event(id: $eventId) {
      registrationTypes(limit: 20) {
        registrations(limit: 20) {
          id
        }
      }
    }
  }

caution

The default value for the limit argument is 100, with a maximum value of 2,000. If your query has a hierarchy of nested array fields, you will quickly exceed the limit for a single operation. Consider setting a lower limit or splitting your operation into multiple requests.

Exceeding the cost limit for a single operation

Executing an operation with a cost greater than 5,000 will result in an error:

HTTP/1.1 500

{
  "data": {},
  "errors": [
    {
      "message": "The operation exceeds the maximum cost of 5000",
      "extensions": {
        "code": "INTERNAL_SERVER_ERROR"
      }
    }
  ]
}

Exceeding the total cost limit within an hour

Executing an operation that exceeds the total cost points for an hour (1,000,000) will result in an error:

HTTP/1.1 500

{
  "data": {},
  "errors": [
    {
      "message": "Exceeds maximum total cost of 1000000 per period of 3600 seconds",
      "extensions": {
        "code": "INTERNAL_SERVER_ERROR"
      }
    }
  ]
}

HTTP response headers

The EventsAir GraphQL API provides three HTTP response headers to help track operation costs and depth limits:

HTTP response header	Description
X-EventsAir-GraphQL-Operation-Cost	The calculated cost for an operation
X-EventsAir-GraphQL-Operation-Cost-Remaining	The remaining cost points available for the next 60 minutes
X-EventsAir-GraphQL-Operation-Depth	The calculated depth of the operation

These response headers can be used to understand the cost of operations executed and track the remaining points within the current hour.