错误码

错误结构

所有错误响应的 JSON 结构都相同：

{
  "error": {
    "code": "insufficient_balance",
    "message": "insufficient balance, please top up"
  }
}

• code 是稳定的，请在代码里据此分支处理。
• message 是给人看的说明，可能调整；记录日志即可，不要解析它。

任何返回错误的调用都不计费。

错误码一览

HTTP	错误码	含义	处理建议
400	validation_error	参数缺失或无效、引擎与结果类型组合不受支持，或抓取的 URL 无法公开访问。message 会指出具体字段，例如 num: Input should be less than or equal to 100。	修正请求，不要原样重试。
401	invalid_api_key	Key 缺失、不存在或已停用，账户被暂停，或请求 IP 不在该 Key 的白名单内。	在 /dashboard/keys 检查请求头和 Key。参见鉴权。
402	insufficient_balance	余额不足以覆盖本次调用的最高可能费用。	到 /dashboard/wallet 充值，或调低 include_content。
404	not_found	资源不存在——例如搜索 ID 不存在、属于其他账户或已超过 30 天。请求未知路径也会返回此错误。	检查 ID 与路径。
429	rate_limited	该 Key 每分钟请求数超限，或已达到 Key 的每日积分上限（daily credit limit for this API key reached）。	按 Retry-After 的秒数等待后重试。若是每日上限，可在 /dashboard/keys 调高，或等到下一个 UTC 日。
502	all_upstreams_failed	我们已尝试本次请求的所有可用通路，均未成功。不计费。	稍后以指数退避方式重试。持续出现时查看 /v1/engines，或换一个引擎。
503	engine_unavailable	引擎尚未上线（baidu），或该结果类型暂时不可用。	换用其他引擎或 engine=auto，并查看 /v1/engines。

使用错误的 HTTP 方法（例如 GET /v1/search）会返回 405，错误码为 validation_error。

重试策略

状态码	是否重试
400、401、402、404	否——先修正请求、Key 或余额。
429	是，等待 Retry-After 秒后重试。
502、503	是，带退避重试（例如 1 秒、2 秒、4 秒，最多 3–5 次）。
其他 5xx	是，带退避重试；反复出现请联系客服。

重试是安全的：失败的调用不收费，重试成功也只计费一次。

import time, httpx

def search(payload, key, attempts=4):
    for i in range(attempts):
        r = httpx.post("https://api.serphubapi.com/v1/search",
                       headers={"X-API-Key": key}, json=payload, timeout=30)
        if r.status_code == 429:
            time.sleep(int(r.headers.get("Retry-After", "1")))
            continue
        if r.status_code >= 500 and i < attempts - 1:
            time.sleep(2 ** i)
            continue
        r.raise_for_status()
        return r.json()
    r.raise_for_status()

获取帮助

请发邮件至 support@serphubapi.com，附上调用 ID（meta.id 或 X-Search-Id，如有）、请求时间和错误码。最近的调用（包括失败的）可在 /dashboard/logs 查到。