认证与错误处理：API Key、错误码与重试策略

采集是异步的：提交 run → 轮询 → 取数。端到端示例见 快速开始，本页是信封/状态/计费/错误的完整参考。

认证方式

所有调用在请求头携带 API Key：

Authorization: Bearer YOUR_API_KEY

获取 API Key

1. 登录 AntsData 控制台
2. 进入 API Keys 页面 → Create New Key
3. 复制生成的 Key（格式 ants_xxxxxxxxxxxx，只显示一次，请妥善保存）

安全建议

• 不要把 API Key 硬编码或提交到 Git；用环境变量存储；定期轮换。

  export ANTSDATA_API_KEY="ants_xxxxxxxxxxxx" # Linux / macOS $env:ANTSDATA_API_KEY="ants_xxxxxxxxxxxx" # Windows PowerShell

  import os, requests API_KEY = os.getenv("ANTSDATA_API_KEY") H = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

统一响应信封

所有响应共用信封，code === 0 即成功：

{ "code": 0, "message": "ok", "data": <object> }

• code == 0 是唯一成功判据（无 success 布尔）。
• 出错时返回对应 HTTP 状态码 + { "code": <int>, "message": <人类可读> }。
• 计费不在信封顶层，而在 run 对象上（chargedCredits/recordCount）。

Run 生命周期

POST /v1/scraper/{平台}/{资源}   → 201 { id, status:"queued" }        创建 run（async，冻结积分）
                                  → 200 { status:"succeeded"|"failed" } sync 阻塞内到终态
                                  → 202 { id, status:"queued"|"running"} sync 超时 fallback（转轮询）
GET  /v1/scraper/runs/{id}       → { status, targetsOk, tasks[], ... } 轮询至终态
GET  /v1/scraper/runs/{id}/records?page=&pageSize=   → 分页记录         succeeded 后取数
GET  /v1/scraper/runs/{id}/download?format=json|csv|excel   → 附件下载

提交返回码取决于 deliveryMode：async 恒 201；sync 到终态 200、超时 fallback 202（详见 quick-start「同步模式」）。

状态机

queued ──▶ running ──▶ succeeded   (终态)
                   └──▶ failed      (终态)

• 仅 4 态：queued / running / succeeded / failed（无 pending/completed/cancelled）。
• 终态为 succeeded | failed；轮询到终态即停。
• 无 progress 百分比：用 targetCount / targetsOk / targetsFailed 计数看进度。

Run 对象字段参考

POST 创建与 GET /runs/{id} 返回同一 Run 对象（data）：

逐目标结果 tasks[]

一个 run 的 N 个 targets 内部展开成 N 个 task，单目标成败在这里（不在结果记录里）：

部分成功：只要有 ≥1 目标成功，run 即 succeeded 并按成功条数出数计费；失败目标在 tasks[] 里各自带 errorMessage。

取数与下载

• 分页记录：GET /v1/scraper/runs/{id}/records?page=1&pageSize=20→ data = { total, page, pageSize, items:[...] }；pageSize 默认 20、上限 100；run 未成功时返回空集。
• 下载：GET /v1/scraper/runs/{id}/download?format=json|csv|excel（默认 json）→ 附件流。
• 结果留存约 90 天，请及时取用。

计费：冻结 → 结算 / 释放

按成功产出的数据条数计费（每 1000 条记录一个单价）：

各端点单价与套餐见定价页面。

错误码

统一信封错误：真实 HTTP 状态码 + {code, message}。

具体业务 code 值沿用平台 errcode（run 域 4000+、积分不足等），最终值以服务端为准。单目标失败不产生顶层错误：run 仍可 succeeded（部分成功），失败细节看 tasks[].errorMessage。

重试策略

import time

def poll_run(base, headers, run_id, max_wait=300):
    waited = 0
    for delay in [1, 2, 5, 5, 5, 5, 5, 5, 5, 5]:
        r = requests.get(f"{base}/scraper/runs/{run_id}", headers=headers)
        if r.status_code >= 500:            # 服务端错误：退避重试
            time.sleep(delay); waited += delay; continue
        run = r.json()["data"]
        if run["status"] in ("succeeded", "failed"):
            return run
        time.sleep(delay); waited += delay
        if waited >= max_wait:
            raise TimeoutError(f"run {run_id} 未在 {max_wait}s 内完成")
    return run

最佳实践

1. 用环境变量存 API Key，不要硬编码。
2. 轮询用指数退避（1s→2s→5s 封顶），别高频空转；设总超时。
3. 一个 run 多目标：targets 批量提交比逐个提交高效，逐目标状态看 tasks[]。
4. 合理设 recordLimit 控制单次成本；0=不限会按可用积分反算冻结。
5. 大结果用 /download，逐页浏览用 /records。

计费与价格

按成功返回的数据条数计费：每返回一条数据按该端点单价扣减，失败记录不计费；实扣体现在 run 的 chargedCredits。各端点单价与套餐详见定价页面。

下一步

• 快速开始 — 端到端提交/轮询/取数示例
• Scraper 平台指南：TikTok · X · Instagram · Facebook · LinkedIn · Google · YouTube · Amazon
• 同步搜索：Google SERP — 一次调用直接返回搜索结果

FAQ

Q: API Key 有有效期吗？

无固定有效期，可随时在控制台撤销与重新生成；建议为不同应用/环境用不同 Key。

Q: 轮询频率有建议吗？

指数退避（1s→2s→5s 封顶），到 succeeded/failed 即停；避免高频空转触发限流。

Q: 采集失败会扣费吗？

不会。全失败释放冻结、不计费；部分成功只按成功产出的条数结算。

Q: 如何查看用量与账单？

登录控制台 Billing 页查看积分消耗与账单明细。

Q: 遇到技术问题怎么联系支持？

控制台提交工单、邮件 [email protected]、或加入 Discord 社区。