Labs 错误任务查询

POST /v3/dataforseo_labs/errors

本接口使用 POST 方法，请求路径为：

POST https://api.seermartech.cn/v3/dataforseo_labs/errors

用于查询过去 7 天返回错误的 Labs API 任务。如果某个任务未出现在结果中，表示该任务未返回错误，或尚未完成。

本接口调用不收费。

请求说明

请求体使用 UTF-8 编码的 JSON 数组格式。所有请求参数应放在数组中的对象。

请求参数

参数	类型	说明
limit	integer	最多返回的错误任务数量。可选，默认值为 1000，最大值为 1000。
offset	integer	结果偏移量。可选，默认值为 0。例如设置为 10 时，将跳过前 10 条结果并返回后续任务。
filtered_function	string	按指定 API 函数筛选错误任务。可填写响应中 function 字段对应的值，例如 dataforseo_labs/related_keywords/live。建议获取未筛选结果，再根据 function 字段进行筛选。
datetime_from	string	错误时间筛选起始时间。可选支持过去 7 天范围的 datetime。使用 UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。示例：2021-11-15 12:57:46 +00:00。
datetime_to	string	错误时间筛选结束时间。可选支持过去 7 天范围的 datetime。使用 UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。示例：2021-11-15 13:57:46 +00:00。

请求示例

[
  {
    "limit": 10,
    "offset": 0
  }
]

响应字段

接口返回 JSON 数据任务列表及每个任务的错误。

顶层响应字段

字段	类型	说明
version	string	当前 API 版本。
status_code	integer	通用状态码。完整状态码列表请参考错误码文档。
status_message	string	通用状态信息。
time	string	请求总执行时间，单位为秒。
cost	float	平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_count	integer	tasks 数组中的任务数量。
tasks_error	integer	tasks 数组中返回错误的任务数量。
tasks	array	任务对象数组。

任务字段

字段	类型	说明
id	string	任务唯一标识，UUID 格式。
status_code	integer	任务状态码，通常位于 10000 至 60000 范围。
status_message	string	任务状态信息。
time	string	任务执行时间，单位为秒。
cost	float	平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_count	integer	result 数组中的数量。
path	array	API 请求路径。
data	object	请求时提交的参数。
result	array	错误数组。

result 错误字段

字段	类型	说明
id	string	错误任务 ID。
datetime	string	错误发生时间，使用 UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。
function	string	对应的 API 函数，例如 dataforseo_labs/related_keywords/live。
error_code	integer	错误码。
error_message	string	错误信息，或导致错误的 URL。
http_url	string	触发错误的请求 URL。
http_method	string	HTTP 请求方法。
http_code	integer	HTTP 状态码。
http_time	float	HTTP 请求耗时。
http_response	string	平台服务器返回的 HTTP 响应。

错误码

响应中的 status_code、任务级 status_code 和 error_code 用于表示请求或任务执行结果。完整错误码列表请参考错误码文档。

请求示例

curl

curl --location --request POST \
  "https://api.seermartech.cn/v3/dataforseo_labs/errors" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "limit": 10,
      "offset": 0
    }
  ]'

Python

import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/errors"

headers = {
    "Authorization": "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
}

payload = [
    {
        "limit": 10,
        "offset": 0,
    }
]

response = requests.post(url, headers=headers, json=payload)

if response.ok:
    result = response.json()
    if result.get("status_code") == 20000:
        print(result)
    else:
        print(
            "请求失败，状态码：%s，信息：%s"
            % (result.get("status_code"), result.get("status_message"))
        )
else:
    print("HTTP 请求失败：%s" % response.status_code)

TypeScript

import axios from "axios";

const response = await axios.post(
  "https://api.seermartech.cn/v3/dataforseo_labs/errors",
  [
    {
      limit: 10,
      offset: 0,
    },
  ],
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
  }
);

const result = response.data;

if (result.status_code === 20000) {
  console.log(result);
} else {
  console.error(
    `请求失败，状态码：${result.status_code}，信息：${result.status_message}`
  );
}

响应示例

{
  "version": "0.1.20220326",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0609 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0123 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "dataforseo_labs",
        "errors"
      ],
      "data": {
        "api": "dataforseo_labs",
        "function": "errors",
        "limit": 10,
        "offset": 0
      },
      "result": [
        {
          "id": "98765432-10fe-dcba-9876-543210fedcba",
          "datetime": "2021-11-15 12:57:46 +00:00",
          "function": "dataforseo_labs/related_keywords/live",
          "error_code": 40100,
          "error_message": "任务执行失败",
          "http_url": "https://api.seermartech.cn/v3/dataforseo_labs/related_keywords/live",
          "http_method": "POST",
          "http_code": 400,
          "http_time": 0.245,
          "http_response": "{\"status_code\":400,\"message\":\"Invalid request\"}"
        }
      ]
    }
  ]
}

实用场景

• 排查批量任务失败原因：按 API 函数筛选错误任务，快速定位研究流程中的失败环节，减少人工排查时间。
• 监控近期 API 任务稳定性：按时间范围查询过去 7 天的错误记录，统计不同接口的失败频率，及时发现服务或参数异常。
• 定位特定时间段的业务障：使用 datetime_from 和 datetime_to 获取障窗口的错误任务，为问题复盘和运维告警提供依据。
• 构建任务失败重试机制：读取 error_code、error_message、http_code 和 http_response，区分可重试错误与参数错误，优化自动重试策略。
• 生成 SEO 数据任务质量报表：汇总 function、错误时间和 HTTP 响应信息，评估不同 SEO 数据采集模块的任务成功率。