API 总览

Base URL

https://openapi.thunderbit.com/openapi/v1

身份认证

所有端点使用 HTTP Bearer（API Key）：

Authorization: Bearer YOUR_API_KEY

请从 Thunderbit 控制台获取你的 Key。Key 可吊销、按环境区分 —— 切勿将生产 Key 嵌入客户端代码。

错误响应结构

所有错误响应共享同一种 envelope。默认采用 LEGACY 格式：

{
  "success": false,
  "error": {
    "code":    "INVALID_URL",
    "status":  400,
    "message": "The provided URL is not valid",
    "details": null
  }
}

Note: 此前文档曾介绍 GOOGLE_RPC 备选 envelope，code 与 status 类型互换（string ↔ number）。该模式 已弃用，不推荐使用 —— 强类型客户端（OpenAPI codegen、Pydantic、serde、encoding/json）会直接反序列化失败。请使用上面的 LEGACY 格式；未来 code: string、status: number 类型保持稳定。 details 字段可能携带结构化上下文 —— 例如，INVALID_PARAMETER 错误时返回字段级校验错误，格式为 { field: message }。

规范错误码

HTTP	Code	含义
400	`INVALID_URL`	URL 格式无效
400	`INVALID_SCHEMA`	JSON Schema 无效
400	`INVALID_PARAMETER`	一个或多个请求参数校验失败
400	`SCHEMA_OR_PROMPT_REQUIRED`	提取时必须提供 `schema`（或 `prompt`）
400	`SCHEMA_AND_PROMPT_EXCLUSIVE`	`schema` 和 `prompt` 不能同时提供
400	`BATCH_SIZE_EXCEEDED`	批量请求超过 100 URL 上限
400	`MALFORMED_REQUEST_BODY`	请求体不是合法 JSON
401	`API_KEY_MISSING`	缺少 `Authorization` header
401	`API_KEY_INVALID_FORMAT`	API Key 格式无效
401	`API_KEY_NOT_FOUND`	系统中找不到该 API Key
401	`API_KEY_REVOKED`	API Key 已被吊销
401	`API_KEY_DISABLED`	API Key 已被禁用
401	`API_KEY_EXPIRED`	API Key 已过期
401	`INVALID_API_KEY`	（已废弃，请使用上面具体的 `API_KEY_` 错误码）*
402	`INSUFFICIENT_CREDITS`	账户额度不足
404	`JOB_NOT_FOUND`	批量任务未找到
404	`RESOURCE_NOT_FOUND`	通用资源未找到
408	`REQUEST_TIMEOUT`	API 请求超时
408	`SCRAPE_TIMEOUT`	目标页面响应超时
422	`SCRAPE_SSL_ERROR`	目标站点存在 SSL/TLS 问题
422	`SCRAPE_DNS_RESOLUTION_ERROR`	无法解析目标域名
422	`SCRAPE_SITE_ERROR`	目标站点返回错误
422	`SCRAPE_EMPTY_CONTENT`	目标页面返回空内容
422	`SCRAPE_CONTENT_TOO_LARGE`	目标页面超过大小限制
422	`SCRAPE_TARGET_FORBIDDEN`	目标站点拒绝访问（403）
422	`SCRAPE_TARGET_NOT_FOUND`	目标 URL 返回 404
422	`SCRAPE_UNSUPPORTED_FILE`	目标文件类型不支持
429	`RATE_LIMIT_EXCEEDED`	触发账户速率限制
429	`SCRAPE_TARGET_RATE_LIMITED`	目标站点对我们的请求做了限流
500	`INTERNAL_ERROR`	通用内部错误
500	`DISTILL_FAILED`	蒸馏流水线失败
500	`EXTRACT_FAILED`	提取流水线失败
500	`PIPELINE_ERROR`	流水线某一步报错
500	`AI_EXTRACTION_FAILED`	AI 提取步骤失败
500	`MARKDOWN_CONVERSION_FAILED`	HTML 转 Markdown 失败
502	`SCRAPE_ALL_PROVIDERS_FAILED`	所有抓取 provider 全部失败
502	`UPSTREAM_BAD_GATEWAY`	上游返回了无效响应
503	`SCRAPE_PROVIDER_UNAVAILABLE`	抓取 provider 不可用
503	`AI_SERVICE_UNAVAILABLE`	AI 服务不可用
503	`DOWNSTREAM_SERVICE_UNAVAILABLE`	下游服务暂时不可用
504	`UPSTREAM_TIMEOUT`	上游网关超时
504	`AI_TIMEOUT`	AI 服务调用超时

重试策略参考

错误类别	是否重试？	如何处理
`4xx`（输入错误）	❌ 否	修正请求后重试
`401`（认证）	❌ 否	重新生成 / 替换 API Key
`402`（额度）	❌ 否	充值
`408` / `504`（超时）	✅ 是	指数退避，最多 3 次
`429`（限流）	✅ 是	等到 `X-RateLimit-Reset` —— 详见速率限制
`5xx`（服务端）	✅ 是	指数退避，最多 3 次
`SCRAPE_TARGET_*`（目标站点）	⚠️ 可能	升级 `renderMode` 后重试一次

API 总览

Base URL

身份认证

错误响应结构

规范错误码

重试策略参考

目录