Rate limits and errors
Codes, retries, limits.
Draft notice
Owner check needed: endpoint, parameter, limit and error names here come from the planning spec, not from the live service. Confirm them against the real API before launch.
Overview
Every error has a code, a message and a retryable flag. All of them cost 0 credits.
- Typed codes with a retryable flag.
- All errors cost 0 credits.
- 3 parallel requests on every plan.
- TikTok can block or change things.
{"success": false, "error": {"code": "private_video", "message": "This video is private.", "retryable": false}}Error body
Error codes
| Code | HTTP | Retryable | Meaning |
|---|---|---|---|
invalid_request | 400 | No | The url is not a TikTok video link or ID, or format is not one of json, srt, vtt, txt. |
unauthorized | 401 | No | Missing or invalid key. |
insufficient_credits | 402 | No | The plan has no credits left. |
private_video | 403 | No | The video is private. |
video_unavailable | 404 | No | Removed, deleted or never existed. |
no_transcript | 404 | No | No caption track, and no speech-to-text for this request. |
language_unavailable | 404 | No | That language is not available; the message lists the ones that are. |
rate_limited | 429 | Yes | Too many requests. Wait for Retry-After seconds. |
upstream_blocked | 502 | Yes | TikTok blocked the request. Retry later. |
upstream_timeout | 504 | Yes | TikTok or the speech-to-text step took too long. |
Codes and statuses are illustrative and to be confirmed. Treat the retryable flag as the rule, not the list.
Limits
Every paid plan allows up to 3 parallel requests. Per-minute limits and the headers that report them are to be confirmed. Honour Retry-After when you get 429.
What can go wrong on TikTok’s side
- TikTok can block requests or change its pages without notice, which shows up as
upstream_blockedorupstream_timeout. - Videos can be made private or deleted after you saved the link.
- No uptime, speed or success rate is promised on this site.
See the batch workflow for a retry loop.
Frequently asked questions
Which errors should I retry?
Retry only errors with retryable true: rate_limited, upstream_blocked and upstream_timeout. Waiting does not fix a private or removed video.
Is a failed call really free?
That is the rule: failed calls cost 0 credits. Verify it with your own test videos before you rely on it.
Ready to call it from your code?
Get API key