Business Data 错误任务查询

通过本接口可查询 过去 7 天返回错误的 Business Data API 任务。

型用途是排查 webhook 投递失败：如果你为任务了 pingback 或 postback，但由于服务端错误未收到回调，可以通过本接口获取出错任务 ID，再结合 /v3/appendix/webhook_resend/ 对这些任务重新发送 webhook。

如果某个任务未出现在返回列表中，通常表示该任务：

• 没有产生错误；
• 或尚未执行完成。

接口说明

• 请求方式：POST
• 请求地址：https://api.seermartech.cn/v3/business_data/errors
• 请求体格式：JSON
• 编码：UTF-8
• 计费：****，调用该接口不会产生费用 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

POST 请求体为 JSON 数组格式：

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

字段说明如下：

字段名	类型	说明
limit	integer	返回的错误任务最大数量。可选，默认值：1000，最大值：1000
offset	integer	返回结果的偏移量。可选，默认值：0。例如设置为 10 时，将跳过前 10 条任务，从后续任务开始返回
filtered_function	string	按指定函数筛选返回错误任务。可使用响应中 function 字段的值进行过滤。示例：hotel_searches/task_post、postback_url、pingback_url
datetime_from	string	结果过滤起始时间。可选。支持最近 7 天范围，格式为 UTC：yyyy-mm-dd hh-mm-ss +00:00。示例：2021-11-15 12:57:46 +00:00
datetime_to	string	结果过滤结束时间。可选。支持最近 7 天范围，格式为 UTC：yyyy-mm-dd hh-mm-ss +00:00。示例：2021-11-15 13:57:46 +00:00

响应结构

服务端返回 JSON 数据， tasks 数组。

顶层字段

字段名	类型	说明
version	string	当前 API 版本
status_code	integer	接口总体状态码，完整列表见 /v3/appendix/errors
status_message	string	接口总体状态信息，完整列表见 /v3/appendix/errors
time	string	总执行时间，单位秒
cost	float	本次请求总费用，单位 USD
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	tasks 数组中返回错误的任务数量
tasks	array	任务结果数组

tasks[] 字段

字段名	类型	说明
id	string	任务唯一标识，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000，完整列表见 /v3/appendix/errors
status_message	string	任务状态说明，完整列表见 /v3/appendix/errors
time	string	任务执行时间，单位秒
cost	float	任务费用，单位 USD
result_count	integer	result 数组中的数量
path	array	URL 路径
data	array	与请求中提交参数对应的数据
result	array	错误结果列表

tasks[].result[] 字段

字段名	类型	说明
id	string	任务 ID
datetime	string	错误发生时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。示例：2019-11-15 12:57:46 +00:00
function	string	对应的 API 函数名
error_code	integer	错误码
error_message	string	错误信息或引发错误的 URL。错误信息完整列表见 /v3/appendix/errors
http_url	string	发生错误的 URL，可能是你调用 API 使用的地址，也可能是 pingback/postback 回调地址
http_method	string	HTTP 方法
http_code	integer	HTTP 状态码
http_time	float	HTTP 请求耗时。对于了 pingback/postback 的任务，该字段表示你的服务器完成响应所用时间
http_response	string	服务端响应

请求示例

cURL

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

Python

import requests

url = "https://api.seermartech.cn/v3/business_data/errors"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "limit": 10,
 "offset": 0,
 "filtered_function": "pingback_url"
 }
]

response = requests.post(url, json=data, headers=headers)
print(response.json)

TypeScript

import axios from "axios";

const postData = [
 {
 limit: 10,
 offset: 0,
 filtered_function: "pingback_url",
 },
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/business_data/errors",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
 data: postData,
})
 .then((response) => {
 // 输出返回结果
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

响应示例

{
 "version": "0.1.20220321",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1538 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "business_data",
 "function": "errors",
 "limit": 10,
 "offset": 0,
 "filtered_function": "pingback_url"
 },
 "result": []
 }
 ]
}

状态码与错误处理

• 顶层 status_code / status_message 表示本次接口调用整体状态
• tasks[].status_code / tasks[].status_message 表示单个任务状态
• result[].error_code / result[].error_message 表示错误
• 完整错误码与说明可参考 /v3/appendix/errors

排查建议：

1. 检查顶层 status_code 是否为 20000
2. 再查看 tasks[].result[] 中的 error_code、http_code、http_response
3. 如果错误与 webhook 投递，可根据返回的任务 ID 调用 /v3/appendix/webhook_resend/ 进行重发

使用说明

• 本接口返回 最近 7 天 的错误任务
• 支持通过 datetime_from 和 datetime_to 缩小排查时间范围
• 如需按错误来源筛选，可通过 filtered_function 指定函数名
• 若首次不加筛选获取结果，可根据返回中的 function 值再次发起过滤查询

实用场景

• 排查回调失败任务：筛选 pingback_url 或 postback_url 错误，快速定位未成功投递的回调任务，减少数据漏收风险
• 重发丢失 webhook：获取出错任务 ID，再结合 /v3/appendix/webhook_resend/ 重发回调，恢复业务链路完整性
• 监控接口稳定性：按时间窗口查询 datetime_from/datetime_to 范围错误任务，评估某时段平台或自有服务的异常
• 定位服务端响应问题：通过 http_code、http_time、http_response 判断是时、5xx 还是参数错误，提升障处理效率
• 按功能模块归因错误：使用 filtered_function 区分不同业务函数的失败，便于 SEO 数据采集、门店信息抓取等流程分别治理