Usage limits
In order to protect EventsAir servers from excessive or malicious calls the EventsAir GraphQL API includes some limits.
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
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 {
# ...
}
}
}
}
}
}
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.
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 theevent
object is40
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, sinceregistrations
are nested withinregistrationTypes
, the resulting cost of theevent
object is20
x20
=400
points.query ExampleQuery($eventId: ID!) {
event(id: $eventId) {
registrationTypes(limit: 20) {
registrations(limit: 20) {
id
}
}
}
}
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 per hour of 500000",
"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.