TikTok Shop

Working within TikTok Shop API rate limits

Every marketplace API has rate limits, and every integration hits them eventually. What separates a robust one from a fragile one is not the limit - it is what you were spending your quota on when you hit it.

Polling is the expensive habit

The naive design asks the API for all orders every few minutes. It works at ten orders a day and collapses at four hundred, because you are spending almost all your quota confirming that nothing has changed.

The fix is to narrow what you ask for. Pull by update time rather than fetching everything, and keep a marker of where you got to. Most calls then return a handful of rows or none.

Back off properly when throttled

A throttle response is not a failure, it is an instruction. Retrying immediately makes it worse - you are adding load to a system that just told you it has too much.

Wait, and wait longer each time. If the response tells you how long to wait, use that number rather than your own guess. And cap the number of retries, because something that has failed six times is not going to succeed on the seventh.

• Respect any retry-after value the API gives you
• Increase the wait on each attempt rather than retrying at a fixed interval
• Give up after a small number of attempts and leave the work pending
• Never retry in a tight loop, which is how a throttle becomes a ban

Separate the urgent from the routine

Not every call deserves the same priority. Uploading tracking against a deadline is urgent. Refreshing the status of an order delivered last week is not.

If you treat them identically, the routine work will occasionally starve the urgent work, and it will do so on your busiest day - because that is when both queues are longest.

Stop asking about finished orders

The largest easy saving is simply not re-checking orders that have reached a terminal state. Delivered is delivered. Cancelled is cancelled. Those rows do not need another call, ever.

In practice this is where most wasted quota goes: a sweep that walks every historical row on every run because nothing marks them as done. Mark them as done.

Design for the day it breaks

Rate limits bite hardest during a spike, which is exactly when you least want the integration to fall over. The behaviour you want is graceful degradation: process what you can, leave the rest queued, report clearly what is outstanding.

An integration that does half the work and tells you honestly is far more useful than one that attempts everything and dies silently.

---