Docs

Error Code Reference

This reference helps you quickly understand error codes returned by the platform, including what each code means, where it comes from, and how to troubleshoot it. Use it to identify common issues across APIs and to find the recommended next step for each error.

Network error codes

Request and downloadFile API

Error code	Error message	Description	Source	Recommended action
10401	Server error	The request finished, but no valid response was returned and no explicit error was provided. This is a fallback error code.	Developer	Verify that the server is running normally, then check the server logs to identify the root cause.
21100	URL not in domain list	The URL’s domain is not included in the trusted-domain whitelist configured in the developer platform.	Developer	Add the domain to the trusted-domain whitelist in the developer platform, or confirm that the URL is spelled correctly.
21101	Destination path has error	The download destination path is invalid because one or more path components are empty.	Developer	Check whether the generated destination path is correct. If the issue comes from an internally generated path, contact the Runtime team for investigation.
21101	Move file failed	Moving the temporary file to the destination path failed.	Developer	Check whether the destination path is already in use, whether the device has enough storage space, and whether directory permissions are correct.
21102	TTNet download progress error	After TTNet creates the download task, the `progress` object is `nil`, so download progress cannot be monitored.	TikTok Client	This is an internal TTNet exception. Retry the download. If the issue continues, contact the Runtime team to investigate TTNet version compatibility.
21103	Request timeout	The request did not receive a response within the specified `timeout` period.	Developer	Check whether the network connection is working properly, consider increasing the `timeout` value, and confirm whether the server is responding too slowly.
21201	Response data error	The download completed, but `filePath` is `nil` and no other error was returned, indicating abnormal response data.	Developer	Retry the download. If the issue persists, it may be caused by an underlying TTNet exception; contact the Runtime team for further investigation.
100000	File path error	The specified `filePath` is not writable because it is not under the `ttfile://user` or `ttfile://temp` directory.	Developer	Make sure `filePath` starts with `ttfile://user` or `ttfile://temp`.
100000	filePath is not supported	A `filePath` parameter was provided, but the current version does not yet support custom download paths.	Developer	Remove the `filePath` parameter and use the default temporary download directory instead. Wait for a later version that supports custom paths.
600003	Network interrupted error	The network connection was interrupted, or the request was canceled explicitly (for example, by calling `request.abort`).	Developer	Confirm whether your business logic intentionally canceled the request. If the cancellation was not expected, check for network interruptions.
600005	Network argv error	The request parameters are invalid. For example: `url` is not a string, `method` is not a supported value, or `data` is of an unsupported type.	Developer	Check the types and formats of all input parameters. Ensure that `url` is a string, `method` is valid, and `data` is a `string`, `object`, or `ArrayBuffer`.
600009	Invalid URL	The URL is an empty string, is malformed and cannot be parsed, or is missing a scheme.	Developer	Check whether the URL is empty, whether it includes a valid `http://` or `https://` prefix, and whether it contains invalid characters.
600011	URL validation error	The URL scheme is not supported, such as `ftp://` or `file://`.	Developer	Change the URL to use `http://` or `https://`.
603301	Exceeded max file size	The downloaded file exceeds the maximum allowed size. The temporary directory limit is 200 MB.	Developer	Make sure the file being downloaded does not exceed 200 MB. If larger files are required, consider downloading them in chunks.

In-App Ads error codes

Init API

Error code	Error message	Description	Source	Recommended action
11001	Param error, invalid ad placement ID	The ad placement ID is empty, so the request parameter is invalid.	Developer	Check whether the ad placement ID is correct.
10001		The ad placement ID validation parameters are invalid.	Developer	Check whether the ad placement parameter type is correct.
20000	Network error	The client request timed out due to a network issue.	TikTok Client	Ask the user to try again later.
20001	Ad placement does not exist	The specified ad placement does not exist.	Developer	Go to the portal and verify that the ad placement ID has been created.
20002	Client key does not match	The ad placement does not match the requested Mini Game ID.	Developer	Go to the portal and verify that the ad placement belongs to the current Mini Game.
20003	Ad placement status is inactive	The ad placement is inactive.	Developer	Go to the portal and activate the ad placement.
20007	Ad placement type does not match	The ad placement type does not match the ad type requested by the SDK.	Developer	Go to the portal and verify that the ad placement type is correct.
30001	Ad placement frequency control calibration failure	Requests for the same ad placement are being made too frequently.	Developer	Check whether the current SDK usage is abnormal or whether the IAA API is being called too often.
50000	Internal error	A server-side internal error occurred.	TikTok Server	Report the error details to the support team for further investigation.

Show API

Error code	Error message	Description	Source	Recommended action
10001	Invalid parameter	The request parameters are invalid. The passed ad instance ID is empty.	Developer	Verify correct SDK implementation against the official documentation
11002	Invalid ad instance ID, not a match	The ad instance ID does not match any existing ad instance.	Developer	Check for uninitialized ad instances.
11003	Ad instance can only show once	This ad instance has already been shown and cannot be reused.	Developer	Check for duplicate usage of the ad instance.
11004	Just showed an ad, can't show now	Not enough time has passed since the previous ad impression, so the interstitial ad cannot be shown yet.	Developer	Verify error handling logic; ensure errors are handled/caught properly
11005	Ad display limit reached, can't show now	The interstitial ad impression limit has been reached, so the ad cannot be shown.	Developer	Verify error handling logic; ensure errors are handled/caught properly
20000	Network error	The client request timed out due to a network issue.	TikTok Client	Try again later
30001	User exit	The user closed the ad before watching it to completion, so no reward was granted.	Developer	Verify error handling logic; ensure errors are handled/caught properly
50000	Internal error	A server-side internal error occurred.	TikTok Server	Forward the error details to the support team

Was this document helpful?