Rate Limits and Quotas
The Webhooks service applies two different kinds of restriction to your app, and it is worth keeping them apart:
- A rate limit restricts how frequently you may call the Webhooks API during a defined period. It is about the speed of your requests.
- A quota restricts how much of a resource you may consume or hold. It is about the amount you accumulate.
Exceeding a rate limit is temporary: wait, and you can call again. Exceeding a quota is not: you have to remove something, or change your design, before you can add more.
Both exist so that all apps calling the Webhooks service receive sufficient service, and so that a runaway app cannot consume excessive resources at the expense of others.
For the exact numbers, see Webhooks Rate Limits. For the platform-wide explanation of rate limiting across APS, see APS Rate Limits and Quotas.
Rate Limiting Is Not Event-Delivery Retrying
These are two unrelated mechanisms that both involve waiting and retrying, and confusing them leads developers to fix the wrong thing.
Rate limiting applies to traffic in the outbound direction: requests your app sends to the Webhooks API. It limits how often you may call an operation. You see it as a 429 Too Many Requests response, and your app is the one that waits and retries. It is documented in this section.
Event-delivery retrying applies to traffic in the inbound direction: notifications the Webhooks service sends to your callback URL. It concerns a delivery that failed, not a request you made. You see it as callbacks that do not arrive and, eventually, a webhook whose status is inactive. The Webhooks service does the retrying, on its own schedule. It is documented in Event Delivery Guarantees.
So a 429 never means a callback failed, and a deactivated webhook never means you were throttled. Nothing you do about rate limits affects delivery retries, and vice versa.
Recognizing a Rate Limit
When your app exceeds a rate limit, the request fails with 429 Too Many Requests. Across APS, a 429 response carries a Retry-After header whose value is the number of seconds after which you can call again, for example Retry-After: 25.
The response body of a rate-limited request is not a sign that your request was malformed. The same request, sent later, succeeds.
Handling a Rate-Limit Response
- Send the request.
- If the response is
429, do not immediately retry. An immediate retry consumes limit you do not have and can extend the period during which you are throttled. - Read the
Retry-Afterheader and treat its value as the number of seconds to wait. - Wait for that period.
- Retry the request once the period has elapsed.
Current APS guidance is to wait for the period given and then retry. Apply that rather than a retry scheme of your own devising, and make sure the wait is real: a loop that retries in a tight cycle while discarding 429 responses is indistinguishable from an attack.
Designing for the Limits
Most apps that hit a Webhooks rate limit are doing avoidable work. The following keeps a normal integration comfortably inside the limits:
- Do not poll the Webhooks API. Repeatedly listing your webhooks to see whether anything changed is the most common source of avoidable requests. A webhook’s configuration only changes when you change it.
- Let callbacks tell you about events, rather than polling another API for them. This is the reason to use Webhooks in the first place. If your app both subscribes to an event and polls the product API for the same information, remove the polling.
- Reuse what you already know. Keep the
hookId,system, andeventof the webhooks you create, so that later operations address a webhook directly instead of listing everything to find it again. - Create webhooks once, not per run. Registering a subscription is a setup step. Creating and deleting webhooks on every job puts sustained traffic on the operations with the lowest limits.
- Spread bulk work. If you have to create or update many webhooks, pace the requests instead of sending them as fast as your client allows.
- Respect
Retry-Afterrather than working around it. - Monitor for repeated
429responses. An occasional429is a burst. A steady stream is a design problem, or a signal that you need a higher limit.
Requesting a Higher Rate Limit
Rate limit increases are available to Autodesk Developer Network (ADN) members. To request one, submit the rate limit change request form through ADN member API support.
Before you submit:
- Analyze your current usage and propose a limit based on it. Arbitrarily chosen large numbers are not accepted.
- Expect a review. The owning product team reviews each request and, if approved, applies the new limit to the specified client ID.
- Approval is not guaranteed. An increase depends on that review.
See APS Rate Limits and Quotas for the platform-wide process.
Next Steps
- Look up an exact limit. Webhooks Rate Limits gives the limit, period, and enforcement scope for each operation, and the quota on webhooks.
- Read the platform-wide guidance. APS Rate Limits and Quotas.
- Understand delivery retries, which are unrelated to rate limiting. Event Delivery Guarantees.
- Reduce the callbacks you receive rather than the requests you send. Callback Filtering.