Errors & rate limits

所有错误带 hint_for_agent —— LLM 调用方可基于此决策下一步。

错误格式

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit: 60 req/min + burst 10. Retry in 5s.",
    "retry_after_seconds": 5,
    "hint_for_agent": "Wait 5 seconds and retry. Pass Idempotency-Key header to safely retry without double-charge.",
    "documentation_url": "https://rp.zgen.xin/docs/errors/rate_limit_exceeded"
  }
}

错误 code 表

HTTP	Code	Hint summary
401	auth_invalid	Set Authorization: Bearer rp-...
404	quota_resource_not_found	Use search endpoint to find IDs first.
422	validation_failed	Required field missing — check schema.
422	extract_empty	URL may be JS-rendered; try /v1/search first.
429	rate_limit_exceeded	Wait retry_after_seconds; pass Idempotency-Key.
402	credits_exceeded	Top up at /dashboard/billing.
502	upstream_failure	Retry exponentially; SDK auto-retries 3×.
504	upstream_timeout	Same as 502.
500	internal_error	Our side; please contact support.

Partial success

多源融合 API partial=true 是常态。HTTP 200 + metadata.warnings[]。

{
  "results": [...],
  "metadata": {
    "partial": true,
    "warnings": [
      {
        "code": "data_source_unavailable",
        "source": "web_search",
        "message": "Web search upstream returned 503; falling back to secondary source",
        "hint_for_agent": "Result is still usable. If you need cross-source coverage, retry in 30s with same Idempotency-Key."
      }
    ]
  }
}

Rate limits

60 req/min sustained + burst 10（token bucket per API key）
响应头 X-RateLimit-Limit / Remaining / Reset
SDK 自动重试 429（按 retry_after_seconds）

Idempotency

传 Idempotency-Key: <uuid> header → 24h 内同 key + 同 body 只扣一次费，安全重放。SDK 自动注入 UUID。

Caching

响应头 Cache-Control: max-age=N 让 SDK 知道缓存多久
Search 系列 5-15 分钟 / Research 系列 24 小时 / Data 系列 1 小时