返回与报错

API返回

事件 API 2.0 的返回中包含以下字段：

|字段{20%}|类型{15%}|描述{65%}|
|---|---|---|
|code |number| 返回码。完整返回码列表及描述，参见 [附录 - 返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|message |string| 返回信息。更多信息参见 [附录 - 返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。 |
|request_id |string| 请求的日志ID，唯一标识一个请求。 |
|data |object| 返回数据。<br><br>若请求成功，本字段将返回空对象（`{}`）。<br>若请求失败，将不返回本字段。 |

API返回码

若想了解 TikTok API for Business 可能返回的全部 API 返回码，请查看附录 - 返回码。

对于成功的请求

若 TikTok 成功接收到事件，API 的返回中将带有 HTTP 状态码200。返回的 body 会包含 API 返回码（TikTok API for Business 返回码）0。

| 返回码{20%} | HTTP 状态码{20%}  | 描述{30%}  | 详情{30%}  |
|---|---|---|---|
| 0 | 200 | 成功 | 请求成功 |

示例

(code Success-Response http)
HTTPS/1.1 200 OK
{
  "code": 0,
  "message": "OK",
  "request_id": "{{request_id}}",
  "data":{} 
}
(/code)

对于失败的请求

若请求失败，您将看到 HTTP 状态码4XX或5XX。返回的 body 将包含对应的返回码，以及解释失败详情的报错信息。若想了解报错详情，请查看返回的 body 中的message字段。

若同一个 API 调用中发送了多个事件，message 字段将提示首个无效事件的（基于 0 的）次序索引。例如，下面的报错信息表示第三个事件的 event_id 为无效字符串。

(code)
{
  "code":40002,
  "message":"Invalid value for data.<span style="background-color: green;">2</span>.event_id: not a valid string.",
  "request_id":"202308291437415F6E70BA7E095091A6F4"
}
(/code)

以下表格列出了事件 API 2.0 的常见报错：

| 返回码{20%}  | HTTP 状态码{20%}  | 报错原因{60%}  |
|---|---|---|
| 40001 | 400 | 没有权限。<br> 您没有操作该广告主账户所需的必要权限。 |
| 40002 | 400 | 有效负载不正确。 <br><br><strong>常见原因</strong>： <ul><li>有效负载不是合法的 JSON 结构。</li><li>缺少必填字段或字段类型错误（例如，要求传入数字，但传入了字符串）。</li><li>对于需要进行 SHA256 散列处理的字段（例如`email`），使用了未经散列处理的值。</li><li>在单个请求中发送了过多的事件（超过1,000）。</li></ul>|
| 40100 | 401 | 请求过多（超过 API 配额限制）。<br><br><strong>常见原因</strong>：达到了接口的频控限制（每秒 1,000 次调用），因此您的请求被限制。 |
| 40104 | 401 | 访问令牌为空。 |

示例

(code Success-Response http)
HTTP/1.1 400 Bad Request
{
  "code": 40002
  "message": "Invalid value for email: not a valid SHA256-hashed string."
  "request_id": "{{request_id}}"
}
(/code)