Overview

Each provider supported by Unipile (LinkedIn, Gmail, WhatsApp, etc.) applies its own rate limits to manage traffic and prevent abuse. If those limits are exceeded, the provider may temporarily block the account, flag it as suspicious, or restrict access — which can lead to degraded service or disconnections.

To avoid this and keep your integrations stable, Unipile enforces its own rate limiting at the Methods API level. Requests that exceed the allowed threshold are rejected by Unipile before they are sent to the provider. This:

Protects your accounts from being throttled or banned by providers
Keeps behavior consistent when calling external APIs
Reduces the risk of errors caused by provider-side limits

For provider-specific quotas and recommendations, see Limits and Restrictions.

Rate limit levels

Unipile can apply up to three levels of rate limiting at the same time. They help prevent abuse and keep usage within each provider’s constraints:

Limit type	Description
Per-method	Generic limit applied to each method individually.
Per-sensitive-method	Stricter limit for specific sensitive methods (e.g. sending messages, invitations). Optional, depending on provider and method.
Per-account	Generic limit applied to all method calls for an account.

Each provider has its own constraints. For example, some providers apply stricter limits when sending messages, so rate limit configurations may vary by provider. Check the Rate Limits section of the dashboard for detailed values and time windows.
Rate limits are enforced using rolling fixed windows: when a request is made and no active window exists, a new window starts. All requests are then counted against that window until it expires, at which point a new window is created on the next request.
You can also use response headers to dynamically adjust your integration’s behavior. See Rate limit for details.
Limits are per account. Hitting a limit for one account does not affect other accounts.
Cached responses do not count toward rate limits. Requests served from cache are not forwarded to the provider. See Manage Cache for details.

When you exceed the limits

API response

When you exceed Unipile’s configured rate limits, the API returns:

HTTP status: 429 Too Many Requests
Error type: api/too_many_requests

When the provider’s rate limiter is hit (e.g. stricter or different window), you get:

HTTP status: 429 Too Many Requests
Error type: provider/too_many_requests

A provider/too_many_requests response means the request was not stopped by Unipile before reaching the provider. In other words, Unipile's configured limit was too permissive for that provider limit or time window. This is the situation Unipile's rate limiter is designed to prevent.

The response body follows the standard error shape (RFC 7807), including type, title, detail, and req_id.

How to handle 429 errors

Identify the source
Use the type field: api/too_many_requests vs provider/too_many_requests.
For api/too_many_requests, follow Unipile's retry instructions
Use the retry-after header to determine when to retry, and use the x-ratelimit-* headers to adapt your request throughput. These headers provide a clear retry window because the request was rejected by Unipile before it reached the provider.
Respect limits
If you often hit api/too_many_requests, consider:
- Using caching for GET requests so fewer calls hit the provider
- Spreading requests over time
- Checking your Rate Limits configuration in the Dashboard
Provider limits
A provider/too_many_requests response does not provide the same predictable retry behavior: the provider's limit has already been reached, so Unipile cannot reliably determine when it will accept another request. Avoid immediate retries, reduce the relevant Unipile limit, and refer to Limits and Restrictions to align your usage with the provider’s quotas.

Configuring rate limits

Rate limits are configurable in the Unipile Dashboard under Rate Limits.

Default: Unipile applies recommended values based on each provider’s limits. These default values are designed to prevent requests from reaching the provider’s rate limiter.
Customization: You can increase these values to match your usage, or revert to the default at any time. Increasing a limit means accepting the risk that requests reach the provider’s rate limiter and return provider/too_many_requests.
Updates: We track provider rate limit changes and update our recommended defaults so your integration stays aligned with upstream constraints.

When a customized limit causes a provider 429, retry handling becomes more complex for your integration: unlike an Unipile 429, Unipile cannot provide a reliable retry time after the provider limit has been reached. Keep the default values whenever predictable retry behavior is required.