响应与错误

每个响应都是同样外层结构的 JSON。成功还是失败看 status 字段，而不是 HTTP 状态码：先判断 status，再读取结果。

公共响应结构

接口成功响应会返回同一套顶层元数据。接口自己的数据只放在 organic、images、news、videos、places 或 place 这类结果字段里。

字段类型出现条件说明

status

必填

number

必填

业务状态码，0 表示成功。

request_id

必填

string

必填

稳定请求 ID，用于支持、重试和日志关联。

elapsed_ms

必填

number

必填

网关观测到的请求执行耗时，单位毫秒。

credits_charged

必填

number | null

必填

退款逻辑处理后实际扣除的点数。null 或 charge_status: unknown 表示尚未确认扣费。

search_type

可选

string

可选

产品返回此字段时，表示该产品的响应类型。

错误

字段类型出现条件说明

error

必填

string

必填

可读错误信息。

SUCCESS

请求成功完成。请检查产品响应字段；no_results 本身不能证明 HTTP 404。

扣费

1000

INVALID_REQUEST

请求体或参数缺失/无效。

不扣费先修正请求再发

1001

UNAUTHORIZED

API key 缺失、无效或已撤销。

不扣费先修正请求再发

1004

NOT_FOUND

网关未注册此路由或资源不存在。

不扣费先修正请求再发

1020

INSUFFICIENT_CREDITS

账号余额不足。

不扣费先修正请求再发

1029

RATE_LIMITED

QPS 或并发限制已触发。

不扣费可以重试

1500

INTERNAL_ERROR

意外的内部服务错误。

不扣费可以重试

1502

UPSTREAM_FAILED

worker 返回上游抓取或解析错误。

不扣费可以重试

1503

SERVICE_UNAVAILABLE

当前没有可用 worker 会话。

不扣费可以重试

1504

UPSTREAM_TIMEOUT

网关等待 worker 结果超时。

不扣费可以重试

JSON

{
  "status": 1001,
  "error": "unauthorized",
  "request_id": "0f3576b2-6e2e-4f1e-bb0e-8cb0d4a60195",
  "elapsed_ms": 0,
  "credits_charged": 0
}

响应头

每个接口响应都带有这些响应头，客户端可以据此控制节奏、判断是否重试，不用解析错误文字。

X-RateLimit-Limit: 你的账户每秒允许的请求数。
X-RateLimit-Remaining: 当前这一秒还能再发多少个请求。
Retry-After: 被拒绝时，建议等几秒再发。
X-SerpBase-Retryable: true 表示原样重发有可能成功；false 表示请求本身要改。

联系客服时

请附上响应里的 request_id（成功和失败的响应都有）以及调用时间。有了它我们几秒钟就能找到那次请求，没有的话只能来回询问。

隐私与留存

搜索词可能用于计费、排障、风控和账号日志。具体留存说明见隐私页面。

超时设置

把 HTTP 客户端的超时设为 60 秒（文档里的代码示例已经这样设置）。每个请求在我们这边最多 30 秒就会结束，返回结果或错误；设 60 秒是给网络留出余量。

大多数请求几秒内就返回，但也有一些要 15～20 秒：Google 响应慢或要求验证时，我们会在这 30 秒内换其他线路重试。超时设得太短，恰好会掐掉那些马上就要成功的请求。
如果客户端先放弃，我们会停止这次请求并退还积分，但你既拿不到结果，也拿不到可以处理的错误。客户端超时不要低于 30 秒。
如果你必须更快拿到结果，就在 Google 搜索接口上传 timeout 参数（1～30 秒）：重试会更早开始以适应你的预算，预算用完时立刻返回 status 1504 且不扣费。客户端自身的超时要比它大。
如果请求仍然失败或超时，重新发送即可；只有成功的那次会扣费。