API (SaaS): Throttling and Quotas
The attachmentAV API (SaaS) applies two kinds of limits to protect the service and ensure fair usage across all customers:
- Throttling limits how many requests you can send per second.
- Quotas limit how many scan requests you can send per month.
The limits that apply to you depend on your plan.
| Plan | Throttle (baseline) | Throttle (burst) | Quota |
|---|---|---|---|
| Medium | 2 requests/second | 5 concurrent requests | 50,000 requests/month |
| Large | 3 requests/second | 5 concurrent requests | 100,000 requests/month |
| XL | 5 requests/second | 10 concurrent requests | 250,000 requests/month |
| XXL | 10 requests/second | 20 concurrent requests | 500,000 requests/month |
Need a higher throughput or scan volume? Contact us.
Throttling (#)
Throttling limits the rate at which you can send requests. It applies to all requests, no matter if they trigger a file scan or not. attachmentAV uses a token bucket algorithm, configured with two values:
- Baseline (rate limit): the average number of requests per second you can send over an extended period of time.
- Burst (burst limit): the maximum number of concurrent requests, i.e. the capacity of the token bucket.
When you exceed the throttling limit, the API responds with HTTP status code 429 Too Many Requests and the body {"error": "Rate limit exceeded."}. The response includes a Retry-After header with the number of seconds to wait before sending the next request. We recommend implementing a retry strategy with exponential backoff to handle throttling gracefully.
Quotas (#)
A quota limits the total number of scan requests you can send per calendar month. The quota resets at the beginning of each month (UTC).
Only requests that trigger a file scan (POST /v1/scan/sync/... and POST /v1/scan/async/...) count against your monthly quota. All other requests, for example polling for a scan result with GET /v1/scan/async/result, do not count.
When you exceed your monthly quota, the API responds to scan requests with HTTP status code 429 Too Many Requests and the body {"error": "Quota exceeded."}. All other requests keep working, so you can still retrieve the results of scan jobs that you submitted before. Upgrade your plan if you need a higher quota.
Send a GET request to the /v1/usage endpoint to retrieve your remaining credits and your quota at any time. This request does not count against your monthly quota.
curl \
-X GET \
-H 'x-api-key: <API_KEY_PLACEHOLDER>' \
'https://eu.developer.attachmentav.com/v1/usage'
{"credits":981,"quota":{"limit":1000,"period":"MONTH"}}
credits(number): The remaining number of scan requests for the current period.quota(object):limit(number): The maximum number of scan requests within a period.period(string): The billing period (e.g.MONTH).
See the API Definition for SDK examples (Java, Python, JavaScript, TypeScript) and the regional endpoints.