About OneTrust Integration Throttling

Event Sequencing Formula

Events are evenly distributed using the formula: 

Delay = 60,000 ms ÷ throttling limit

The first event always executes immediately. Every subsequent event gets placed in a queue with an increasing delay, and the event status is set to RATE_LIMITED until it is picked up and processed.

RATE_LIMITED is expected behavior

Events in RATE_LIMITED are waiting to be processed and are not failures. Under normal conditions, all events within the throttle limit should process within approximately one minute.

Throttling is configured per workflow

Each workflow must be configured independently. Enabling throttling on the main workflow does not automatically apply to subflows or webhook workflows.

Throttling controls execution rate - not total API calls

Throttling controls how many workflow executions happen per minute. If each workflow execution makes multiple API calls, total API usage may exceed the configured throttle limit. If the external API's rate limit is lower than this, you need to set a much lower throttle limit to stay under the API's rate limit.

Multiple workflows can impact the same external API

Throttling one workflow does not prevent other workflows from exceeding rate limits when combined. Throttling only governs the rate of a specific workflow. If you have multiple workflows calling the same external API, each workflow's traffic will be combined. 

External and platform rate limits must be considered

External API limits must be validated separately, and tenant-wide limits may also apply across all API usage. OneTrust enforces a global rate limit across all APIs per tenant. This is a combined limit, not per endpoint. If you are seeing 429 errors, it may be because your total API usage across all sources is exceeding this limit. For more information, see OneTrust Rate Limiting.

Throttling can affect downstream event flow

When workflows trigger subflows or webhooks, throttling influences how many events are sent downstream, but not how those workflows execute.  If your workflow is halted, it means it experienced multiple consecutive failures. You can resume it from the workflow details page. Pending throttled events will begin processing once the workflow is active again. 

Queued events follow a throttled lifecycle

With throttling, events move through the following:

Queued → RATE_LIMITED → In Progress → Success/Failure

Shared throttle queue

Throttled events are processed in a shared system queue with limited processing capacity, which can introduce delays during high load. Previously rate limited events will be processed after timeout has elapsed.

Processing delays may exceed expected timing

Events may remain in RATE_LIMITED longer than calculated during peak system usage.

Throttle rates impact on future events

The system will take in new events and perform a check, then events will be throttled at the new rate and resume processing once timeout has elapsed.

Minimum throttle limit constraints

The application has a minimum throttling limit, so setting lower values may require assistance from OneTrust. Make sure your chosen limit supports your expected volume. Once it is set, processing cannot be sped up.

Reduced throughput at low limits

Lower throttle values significantly reduce how many events can be processed per hour or day, increasing the likelihood of backlogs.

Large payloads can delay processing

Events with large payloads may take longer to execute and slow down other events in the queue.

Disabling throttling under load can cause failures

Removing throttling while events are queued can result in bursts of execution, leading to API errors and workflow disruption. When an event is throttled, the status becomes RATE_LIMITED. Events remain in this status until the specified timeout duration. Upon timeout, the system will identify if there are active workflows and resume processing. If there are no active workflows, these events will be dropped.

1. Avoiding API Rate Limit Errors

Customers enable throttling to control how many requests are sent to external systems and prevent 429 errors. 

2. Handling High-Volume or Burst Traffic

Throttling helps distribute event processing over time instead of overwhelming systems with spikes of requests. 

3. Aligning with External System Capacity

Customers adjust throttle limits based on how many requests downstream systems can handle, especially when workflows make multiple API calls. 

4. Creating Predictable and Controlled Processing Behavior

Even spacing of events provides consistent execution patterns, making processing easier to monitor and manage. 

5. Managing Integrations with Unknown or Variable Limits

External API limits may not always be visible in the platform, requiring customers to validate limits independently and configure throttling accordingly. 

6. Controlling Event Flow Across Connected Workflows

When workflows trigger subflows or webhooks, throttling helps regulate how many events are passed downstream without changing how those workflows execute. 

7. Preparing for Large-Scale Data Processing

Customers use throttling alongside batching strategies to ensure large imports or high-event volumes are processed without overwhelming external systems.