Authentication

Every request to the TikTok Marketing API must carry a valid access token. Tokens are long-lived, personal, and bound to the set of advertiser accounts you are allowed to see — all 10 Nova Play accounts in this programme.

Access-Token header

Send the token in the Access-Token HTTP header. Header names are case-insensitive, so access-token works as well. The token is not accepted as a query parameter.

GET /open_api/v1.3/oauth2/advertiser/get/
Host: business-api.huydata.com
Access-Token: $TIKTOK_ACCESS_TOKEN

Header	Required	Description
Access-Token	Yes	Your personal access token. Treat it like a password: do not commit it to a repository, do not paste it into chat or screenshots. Read it from an environment variable.

Verifying the token

The simplest way to check that your token works is to list the advertisers it can access:

curl -s "https://business-api.huydata.com/open_api/v1.3/oauth2/advertiser/get/" \
  -H "Access-Token: $TIKTOK_ACCESS_TOKEN"

Success (code is 0):

{
  "code": 0,
  "message": "OK",
  "request_id": "6e596d719a0141599ce7",
  "data": {
    "list": [
      {"advertiser_id": "7643153585721644371", "advertiser_name": "Dragon Merge Saga (Android)"},
      {"advertiser_id": "7548458757843580535", "advertiser_name": "Idle Mining Empire (Android)"},
      ...
    ]
  }
}

Authentication errors

Authentication failures are returned with HTTP 200 and code 40105. There are two messages:

Header missing:

{
  "code": 40105,
  "message": "Access token is missing. Pass it in the Access-Token header.",
  "request_id": "650da4d05e01495cbd04",
  "data": {}
}

Header present but the token is unknown (typo, wrong environment, revoked):

{
  "code": 40105,
  "message": "Access token is incorrect or has expired.",
  "request_id": "431ccfb3a0ca43c6b6b2",
  "data": {}
}

A 40105 is not retryable: fix the token and call again. Any other code means the token itself was accepted.

Rate limit

The token is also the unit of rate limiting: 60 requests per rolling 60-second window per token, across all endpoints. The 61st request receives code 40100 with the message Too many requests. Please retry after N seconds. Wait the indicated number of seconds (at most 60) and retry. Details are in Errors & rate limits.

Python example

A minimal session that sends the header on every call and raises on any non-zero code:

import os
import requests

BASE = "https://business-api.huydata.com/open_api/v1.3"
session = requests.Session()
session.headers["Access-Token"] = os.environ["TIKTOK_ACCESS_TOKEN"]

def call(path: str, **params) -> dict:
    """GET an endpoint and return `data`. Raises if the API reports an error."""
    resp = session.get(f"{BASE}{path}", params=params, timeout=30)
    body = resp.json()
    if body["code"] != 0:
        raise RuntimeError(f"TikTok API error {body['code']}: {body['message']} (request_id={body['request_id']})")
    return body["data"]

advertisers = call("/oauth2/advertiser/get/")["list"]
print(advertisers[0])
# {'advertiser_id': '7643153585721644371', 'advertiser_name': 'Dragon Merge Saga (Android)'}

requests URL-encodes parameter values for you. When a parameter must be a JSON-encoded list, build it with json.dumps(...) before passing it (see Reporting).