UniLink API Rate Limits (Understand and Handle Throttling)

UniLink enforces per-hour request limits to keep the API fast and fair — understanding the limit headers and retry strategy keeps your integration running smoothly.

Rate limiting is how UniLink protects the API's performance and availability for all users. Without limits, a single runaway script could degrade the experience for every other developer using the platform. UniLink's rate limit system is transparent — every response tells you exactly how many requests you have left and when your quota resets — so building integrations that stay inside the limits is straightforward once you know where to look.

What Rate Limiting Does

Every UniLink API key is subject to a rolling hourly request limit. The counter resets once per hour from the time of your first request in that window. Free plan accounts receive 100 requests per hour, which is enough for manual testing and low-frequency automations. Pro plan accounts receive 1,000 requests per hour, covering most CRM syncs, content management scripts, and analytics pulls. Business plan accounts receive 10,000 requests per hour, supporting high-volume agency workflows, bulk imports, and real-time data pipelines.

Every API response — whether successful or an error — includes three rate limit headers. X-RateLimit-Limit shows the total requests allowed in the current window. X-RateLimit-Remaining shows how many requests you can still make before being throttled. X-RateLimit-Reset is a Unix timestamp indicating when the window resets and your full quota is restored. Reading these headers before each request is the right way to implement proactive throttling in your application — slow down or pause when remaining drops below a safety threshold rather than waiting for a 429.

When you exceed the rate limit, the API returns HTTP 429 Too Many Requests. The response body contains an error object: {"error": "rate_limit_exceeded", "message": "Too many requests. Retry after X seconds.", "retry_after": 1234567890}. The retry_after field is the same Unix timestamp as X-RateLimit-Reset. Do not retry immediately — sleep until the reset time, then resume with normal request pacing. Retrying too fast while rate limited does not consume additional quota but does generate unnecessary 429 responses.

How to Get Started

1. Make any API request and inspect the response headers. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset regardless of the endpoint or HTTP method used.
2. Add header-reading logic to your HTTP client. In most libraries this is a one-time setup — store the remaining count and reset timestamp from each response in a shared variable your request function checks before firing.
3. Implement a pre-request check: if X-RateLimit-Remaining is 0, sleep until X-RateLimit-Reset before sending the next request.
4. Add a 429 handler to your error handling code. When you receive a 429, read retry_after from the response body (or X-RateLimit-Reset from the headers) and wait that long before retrying.
5. Test your backoff logic deliberately by sending more requests than your plan allows in a short period in a development environment. Confirm your code pauses and then resumes correctly.

How to Handle Rate Limits in Code

1. Read headers after every request. Update a shared remaining counter and reset_at timestamp from the response headers on every successful call, not just on errors.
2. Implement exponential backoff for 429 responses. On the first retry, wait 1 second. On the second retry, wait 2 seconds. On the third, wait 4 seconds. Cap at 60 seconds. Add random jitter (±25%) to prevent thundering-herd behavior when multiple instances restart simultaneously.
3. Use bulk endpoints for high-volume operations. Instead of creating 50 contacts with 50 individual POST requests, use the bulk contact import endpoint available on Pro and Business plans to send them all in a single request.
4. Queue and pace requests in batch jobs. If you are processing a large export, add a small delay between requests (for example, 1 request per 3.6 seconds on Free) to stay comfortably inside the hourly limit without needing to handle 429 errors at all.
5. Monitor your usage over time. The dashboard shows request counts per API key. If a key is consistently near its limit, either optimize your integration to make fewer requests or upgrade your plan.

Key Settings

Get the Most Out Of Rate Limit Management

Track your rate limit usage per integration, not per account. If you have five API keys and one of them is consuming 80% of your hourly quota, that integration is a candidate for optimization. Look for polling loops that could be replaced with webhooks, requests that fetch more data than needed (over-fetching), or missing pagination — fetching page after page when you only need the first few results.

Exponential backoff with jitter is the industry-standard approach to handling 429 errors, and it matters especially in multi-instance deployments. If you run three worker processes and all of them hit the rate limit at the same time, a fixed retry delay will cause all three to retry simultaneously and immediately exceed the limit again. Adding random jitter spreads the retries across time so the load recovers gracefully.

Request batching is the single most effective optimization for high-volume workflows. The UniLink bulk endpoints accept arrays of resources — contacts, pages, and orders can all be submitted in batches. Sending 100 records in 1 request instead of 100 separate requests reduces your quota consumption by 99x for that operation. Bulk endpoints are available on Pro and Business plans and are documented in the API reference for each resource type.

Consider using different API keys for different priority levels in your system. For example, use one key for your customer-facing real-time features (page data, checkout) and a separate key for background batch jobs (analytics exports, CRM syncs). If the background key gets rate limited, it does not affect the customer-facing key's quota at all, and your end-user experience stays reliable.

Troubleshooting

• Rate limits are 100/hour (Free), 1,000/hour (Pro), and 10,000/hour (Business) per API key.
• Read X-RateLimit-Remaining and X-RateLimit-Reset headers after every response to stay ahead of the limit.
• A 429 response means you are out of quota — wait until retry_after before sending more requests.
• Use exponential backoff with random jitter when retrying after a 429.
• Replace polling loops with webhooks and use bulk endpoints to minimize request consumption.