Skip to main content

Rate Limiting

API rate limiting protects an Agility instance from misuse and gives every caller fair, predictable access. On Digital.ai-hosted instances, rate limiting is in effect with the hosted limits below. On-premises, it's off until an administrator enables it and configures quotas in the instance's application settings. Either way, any authenticated member can check the policy in force, and a member with the ManageConfig privilege can retrieve usage metrics. Where rate limiting isn't enabled, every endpoint on this page returns 404.

Hosted Limits​

Digital.ai-hosted instances apply these limits per access token:

  • 600 requests per 60 seconds
  • 600 MB of data retrieved per 60 seconds
  • 600 seconds of total response time per 60 seconds
  • 20 errors per 60 seconds

Call QuotaPolicy to see the policy in force on your instance.

How Rate Limiting Works​

Where enabled, quota policies cap API usage by request time, size of data returned, number of requests, and number of errors returned, each over a set duration (for example, 60 seconds). Agility tracks these metrics per API consumer and checks them against the configured policies.

When a caller exceeds a limit, Agility returns an HTTP 429 error that identifies which limit was exceeded and how long to wait before retrying. For example, exceeding a threshold of 20 errors within 60 seconds returns:

{
  "Reason": "ErrorLimit",
  "Message": "API request quota exceeded. Maximum of 20 errors per 60 second(s)",
  "RetryAfter": "50"
}

Reason is one of RequestLimit, ByteLimit, DurationLimit, or ErrorLimit, and a V1-Limit-Reason response header carries the same value. Honor RetryAfter and back off rather than retrying immediately.

Check Configured Quota Policies​

Any authenticated user can call /RateLimit.mvc/QuotaPolicy to retrieve the quota policies configured for the instance, returned as XML:

<throttlePolicy trackAllRequests="True" accessToken="True">
  <quotas>
    <add duration="60" requestLimit="10" byteLimit="10000" errorLimit="5" />
    <add duration="1" requestLimit="5" />
  </quotas>
</throttlePolicy>

Check Your Current Quota Usage​

Any authenticated user can call /RateLimit.mvc/CurrentQuota to retrieve the quotas being tracked for the access token that made the request. TotalDuration is in milliseconds:

[
  {
    "InitiatedDate": "2023-05-31T17:05:35.1131409Z",
    "Expires": "2023-05-31T17:06:35.1131409Z",
    "Data": {
      "TotalRequests": 1,
      "TotalDuration": 60,
      "TotalErrors": 0,
      "TotalSize": 1568
    }
  }
]

Retrieve API Usage Metrics​

A member with the instance-wide ManageConfig privilege can call the following endpoints to see which members are using the API, how many calls they're making, and which requests are being rejected. They report data only when the quota policy sets trackAllRequests="True".

Usage Totals per Member​

/RateLimit.mvc/TrackedRequestStats returns total counts per member for all API requests accumulated since the last IIS application pool restart:

[
  {
    "UserIdentity": "Member:20",
    "Bytes": 10568,
    "Requests": 40,
    "Duration": 2592,
    "Errors": 0,
    "Rejections": 4
  }
]

Tracked Quotas per Member​

/RateLimit.mvc/SystemBuckets returns the quotas being tracked per member, for all members:

[
  {
    "ClientIP": "127.0.0.1",
    "UserIdentity": "Member:20",
    "Buckets": [{ "...": "quota 1" }, { "...": "quota 2" }]
  }
]

Tracked Quotas and Usage Totals Combined​

/RateLimit.mvc/SystemRequestStats returns the quotas being tracked and the total counts per member, accumulated since the last IIS application pool restart:

[
  {
    "ClientIp": "127.0.0.1",
    "CurrentBuckets": [{ "...": "quota 1" }, { "...": "quota 2" }],
    "UserIdentity": "Member:20",
    "Requests": 40,
    "Bytes": 10568,
    "Duration": 2592,
    "Errors": 0,
    "Rejections": 4
  }
]