Quotas are daily and tier-based
Each plan has a daily request allowance, and requests count against it whether or not they succeed. A retry loop against a permanent failure will burn a day's quota surprisingly fast.
Check `/v1/usage` rather than counting locally. Your own counter drifts the moment a request times out and you are unsure whether it landed.
Back off, do not hammer
When you are rate-limited, wait and retry with an increasing delay — double it each time, with a cap. Retrying immediately makes the situation worse for you and everyone else on the key.
Add a small random jitter to the delay. Without it, everything that failed together retries together, and you rebuild the spike you were trying to avoid.
- 1
Respect the response
If a response tells you how long to wait, wait that long. A server-supplied delay beats any heuristic you invent.
- 2
Grow the delay
Double the wait on each attempt — one second, two, four — up to a ceiling. Stop after a small number of attempts rather than retrying forever.
- 3
Jitter it
Randomise the delay slightly so concurrent clients do not synchronise into a thundering herd.
Permanent versus temporary
Some failures will never succeed no matter how many times you try. Private content, deleted posts, and links that require a login are permission boundaries — retrying is pure waste, and it spends quota.
Temporary failures are worth retrying: timeouts, rate limits, and transient upstream errors. These usually clear on their own.
Encode this distinction explicitly in your client. The common bug is a blanket retry that treats a deleted video like a network blip and burns hundreds of requests discovering it is still deleted.
Degrade honestly
When something fails permanently, tell the user what happened in terms they can act on: the post is private, or it was removed. 'Something went wrong' sends people to support with nothing useful.
When you are out of quota, say so rather than presenting it as a failure of the content. They are different problems with different fixes.
Common questions
- Do failed requests count against my quota?
- Assume they do. Build on that assumption and a retry storm cannot quietly consume a day's allowance.
- How many times should I retry?
- A small number — three or four — with an increasing delay, and only for failures that could plausibly clear. Anything permanent should fail on the first attempt.