Guide

Errors

Errors use plain HTTP status codes and a short machine-readable code. A call that fails is never charged.

What an error looks like

400 Bad Request

{
  "error": {
    "type": "invalid_request",
    "message": "region must be one of the 17 supported markets"
  }
}

Branch on error.type. The message is written for people and can change.

Status	Code	Cause	Fix
400	`invalid_request`	An argument is missing or not valid, or the market is not one of the 17.	Fix the argument the message names.
401	`unauthorized`	No key, or the key is not valid.	Send your key in `X-API-Key`. See authentication.
402	`credits_exhausted`	Your credits have run out.	Upgrade, or wait for your credits to renew.
403	`plan_required`	The REST API needs a Pro or Enterprise plan.	Change your plan.
404	`not_found`	The route does not exist, or the id names nothing.	Check the path against this reference.
429	`rate_limited`	Too many requests this minute.	Wait the `Retry-After` seconds. See limits.
429	`too_concurrent`	Too many requests at once.	Wait the `Retry-After` seconds, or run fewer calls in parallel.
502	`upstream_failed`	The tool ran but TikTok could not answer, or the input names nothing.	Retry, or check the id. Refunded.
503	`server_busy`	The API is busy for a moment.	Retry in a few seconds.

Retry 429, 502 and 503. For 429, wait the Retry-After seconds first. Do not retry 400, 401, 402 or 403 without changing something.