// 文档
错误与限制
HTTP 错误、批次错误，以及公开 API 的限额规则。
公开 API 的错误统一返回 { "error": "<机器可读信息>" } 和常规 HTTP 状态码。批次级业务错误在 202 或 429 响应体内通过 batchError 返回。
HTTP 状态码
| 状态码 | error 值 | 原因 |
|---|---|---|
| 400 | invalid json、urls must be a non-empty string array、idempotency-key required、idempotency-key must be 255 characters or fewer | 请求体或幂等键头未通过校验 |
| 401 | missing bearer token、invalid api key | 缺少 Authorization: Bearer 头，或密钥不存在 |
| 403 | api key lookup failed、scope denied | 密钥查询失败，或密钥缺少所需 scope |
| 404 | not found | 任务 ID 不存在或属于其他账号 |
| 409 | idempotency conflict | 同一 Idempotency-Key 携带了不同请求体 |
| 413 | batch too large | 超过 100 条 URL，或请求体超过约 900 KB |
| 425 | request is still processing | 相同幂等键的请求仍在处理，按 Retry-After 秒后重试 |
| 429 | rate limit exceeded | 请求过多，遵守 Retry-After 头 |
| 500 | processing failed、task lookup failed | 服务端失败，幂等重试会回放同一错误 |
批次错误
整批因账号或账单限制失败时，POST /api/v1/urls 返回 429 并带 batchError。202 响应也可能带有 batchError: null 和逐条 rejectedUpfront。
batchError | 原因 |
|---|---|
batch_too_large | 单次请求超过 100 条 URL |
first_order_limit | 超过 50 条的批量要求账号至少有一笔已付款订单 |
daily_limit | 超出账号每日 2,000 条提交上限 |
insufficient_credits | 积分余额或待处理量无法覆盖该批次 |
account_unavailable | 账号被封禁或不可用 |
限流
两级滑动窗口限流，默认窗口均为一分钟。
| 限流 | 默认值 | 维度 |
|---|---|---|
| 按 IP | 30 次/分钟 | publicApiIp |
| 按 API 密钥 | 120 次/分钟 | publicApiKey |
429 响应附带 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset 和 Retry-After 头。
逐条拒绝原因
入校时被拒绝的 URL 出现在 rejectedUpfront 中，不消耗积分。完整表格见 提交 URL。