Imagine you're in a busy coffee shop, and the barista can only take a certain number of orders at a time to keep things running smoothly. If too many people place orders at once, the shop slows down or might even stop serving for a bit to catch up. This is similar to how API rate limiting works.

Rate limiting is the set of rules that control how many requests a user or system can make to an API within a specific time frame. By enforcing these limits, APIs prevent overloads, ensure fair usage, and keep the system working efficiently for everyone. In this article, we'll go over how to handle API rate limiting within your Tines stories.

Before getting started, we recommend familiarizing yourself with the functionality this article covers:

By leveraging HTTP Request action options like retry_on_status and retries, you can handle rate limits gracefully. The retry_on_status option tells the action which HTTP status codes should trigger a retry. The retries option lets you customize the maximum number of retry attempts. Both are available by clicking + Option at the bottom of the action's config panel.

For example, if an API returns a 429 ("Too Many Requests") response, you can configure the HTTP Request action to automatically retry with exponential backoff by adding 429 to the retry_on_status array.

In this video, we show how to apply these two options for an HTTP Request action that returned a 429 response code.

Sometimes it's necessary to explode an array to feed individual values into an HTTP Request action, one at a time. When you do this, all the exploded events will try to process at once, which can trigger rate limits.

By adding a delay after the explode, you can control the pace. The Event Transform action's delay mode accepts a seconds option that supports formulas, so you can create dynamic delays. For example, you can reference the Explode action's index value and use basic math to space out your requests (e.g., adding five seconds per index so that each event is delayed slightly longer than the one before it).

In this video, we look at an example of building a dynamic delay in a story.

Throttle mode lets you control the rate at which events are emitted, regardless of how many events are queued up. For API rate limiting, this is useful when you want to set a fixed pace, for example, allowing only a certain number of events per minute to pass through to a downstream HTTP Request action.

You configure throttle mode by setting runs_per_minute and events_per_run. The throttle applies across all story runs, so even if multiple runs are queued, the rate stays consistent.

In this video, we look at an example of applying a throttle in a story.

Tines gives you multiple options for managing API rate limiting. You can handle it reactively using retry_on_status to recover from rate limit errors, or proactively by using delays and throttles to control request pacing before hitting the limit. As you continue building, choosing the right approach (or combining them) will depend on the API you're working with and its specific rate limiting rules.