SeerMarTech API 文档

主题

错误码 ​

GET /v3/appendix/errors

本接口使用 GET /v3/appendix/errors 获取本平台 API 可能返回的 HTTP 状态码、状态码及对应说明。

该接口返回错误码单和通用状态信息。建议将错误码及响应写应用日志，并针对不同异常设计重试、告警、参数修正或人工介机制。

> 说明： 除以下特殊外，本平台 API 服务通常始终返回 HTTP 200。请求是否成功，应结合响应体中的 status_code、status_message 以及任务级状态进行判断。

HTTP 响应状态码 ​

状态码消息说明
401Unauthorized未授权访问资源，请检查认证信息。
402Payment Required账户扣费失败，请检查账户余额或计费状态。
404Not Found请求的接口路径不存在。
500Internal Server Error服务错误，暂时无法处理请求，请稍后重试。

除 HTTP 200 外，本平台还会在响应体的 status_code 和 status_message 字段中返回状态码和状态消息。

> 说明： 状态消息可能根据触发错误的事件扩展，返回文本可能与下表中的基础描述略有差异。

##部状态码

状态码消息说明
20000ok.请求已成功完成。
20100task created.请求成功，任务已创建。
40000you can set only one task at a time.单次 POST 请求中只能提交一个任务。
40001this id is used by another client, check the id.任务标识符 id 已被当前客户端的任务使用。
40002this id is used by another search engine, check the path.任务标识符 id 已被搜索引擎使用，请检查请求路径。
40003this id is used by another search type, check the path.任务标识符 id 已被搜索类型使用，请检查请求路径。
40004this id is used by another function, check the id.任务标识符 id 已被功能使用，请检查任务标识符和请求路径。
40006you can set no more than 100 tasks at a time.单次 POST 请求最多可 100 个任务。
40100you are not authorized to access this resource.无权访问请求资源，请检查认证信息。
40101internal se server error.请求的搜索引擎无法处理请求并返回错误。
40102no search results.未找到与请求条件匹的搜索结果。
40103task execution failed, please try to resubmit the task.任务执行失败，请使用相近参数重新提交任务。
40104please verify your account before using the api.新用户需要完成邮箱和/或手机号验证后才能使用 API。
40105The task was deleted and is no longer available.请求的任务已从系统中删除，无法继续访问。
40106Task completed with partial results. Some pages could not be retrieved after several retry attempts.任务已完成，但部分页面在多次重试后仍无法获取。未返回页面对应的费用不会计扣费。

40106 部分结果示例 ​

例如，请求获取 100 条搜索结果，但最终只成功解析 80 条，则接口会返回这 80 条结果，并使用 40106 表示部分结果。未成功解析的 20 条结果不会产生费用。

获取错误码列表 ​

调用以下接口可获取当前可用的错误码及说明：

http
GET https://api.seermartech.cn/v3/appendix/errors

本接口不收取调用费用。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

响应字段 ​

接口返回 JSON 数据整体请求信息和 tasks 任务数组。

顶层字段 ​

字段名类型说明
versionstringAPI 当前版本。
status_codeinteger请求的通用状态码。
status_messagestring请求的通用状态消息。
timestring请求总执行时间，单位为秒。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_countintegertasks 数组中的任务数量。
tasks_errorintegertasks 数组中返回错误的任务数量。
tasksarray任务对象数组。

任务字段 ​

字段名类型说明
idstring任务标识符，使用 UUID 格式。
status_codeinteger任务状态码，通常在 10000 至 60000 范围。
status_messagestring任务级状态消息。
timestring任务执行时间，单位为秒。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_countintegerresult 数组中的数量。
patharray请求使用的 URL 路径信息。
dataarray请求任务时提交的参数，通常与 POST 请求体中的参数一致。
resultarray结果数组。
result[].codeinteger错误码。
result[].messagestring错误消息。

请求示例 ​

cURL ​

bash
curl --location --request GET "https://api.seermartech.cn/v3/appendix/errors" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json"

PHP ​

php
<?php

$ch = curl_init('https://api.seermartech.cn/v3/appendix/errors');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPGET => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer smt_live_YOUR_KEY',
        'Content-Type: application/json',
    ],
]);

$response = curl_exec($ch);

if ($response === false) {
    echo '请求失败：' . curl_error($ch);
} else {
    // 解析并处理错误码列表
    $result = json_decode($response, true);
    print_r($result);
}

curl_close($ch);

TypeScript ​

typescript
import axios from "axios";

axios
  .get("https://api.seermartech.cn/v3/appendix/errors", {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
  })
  .then((response) => {
    // 处理接口返回结果
    console.log(response.data);
  })
  .catch((error) => {
    console.error("请求失败：", error.response?.data || error.message);
  });

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/appendix/errors"
headers = {
    "Authorization": "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
}

response = requests.get(url, headers=headers)

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 请求失败：", response.status_code, response.text)

C# ​

csharp
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

public class AppendixErrorsDemo
{
    public static async Task Main()
    {
        using var httpClient = new HttpClient();

        httpClient.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Bearer", "smt_live_YOUR_KEY");

        var response = await httpClient.GetAsync(
            "https://api.seermartech.cn/v3/appendix/errors"
        );

        var responseText = await response.Content.ReadAsStringAsync();

        if (response.IsSuccessStatusCode)
        {
            // 处理 JSON 响应
            Console.WriteLine(responseText);
        }
        else
        {
            Console.WriteLine(
                $"HTTP 请求失败：{(int)response.StatusCode} {response.ReasonPhrase}"
            );
        }
    }
}

响应示例 ​

json
{
  "version": "0.1.20260902",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0665 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0010 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "appendix",
        "errors"
      ],
      "data": {
        "api": "appendix",
        "function": "errors"
      },
      "result": [
        {
          "code": 20000,
          "message": "ok."
        }
      ]
    }
  ]
}

错误处理建议 ​

  1. 优检查 HTTP 状态码，处理认证失败、余额不足、路径不存在和服务端错误。
  2. HTTP 状态码为 200 时，继续检查顶层 status_code。
  3. 对任务型接口同时检查任务对象中的 status_code 和 status_message。
  4. 对 40101、40103 等临时性错误实施有限次数的指数退避重试。
  5. 对 40001 至 40004 等参数或任务标识冲突错误，修正请求后再提交。
  6. 对 40106 部分结果状态，按已返回结果继续处理，并记录未获取数据的。

实用场景 ​

  • 初始化错误码映射表：在系统部署时同步完整错误码，统一前端提示、日志记录和异常分级处理。
  • 监控接口健康状态：定期检查错误码列表和接口响应，及时发现认证、计费或服务异常。
  • 自动编排重试策略：根据 40101、40103 等状态码区分可重试错误与需修正参数的错误，降低任务失败率。
  • 识别部分结果任务：针对 40106 标记数据不完整的 SEO 任务，触发补采、人工复核或结果降级处理。
  • 构建运营告警面板：聚合 API 错误码、任务错误数量和错误消息，定位、排名或搜索结果采集流程中的问题。

统一入口：官网 · LLM API · 控制台

© 2026 SeerMarTech · GEO · SEO 营销数据 API