返回中文文档

速率限制

限流行为

API 使用用量限制来保护稳定性和公平性。超过限制时，API 会返回 429，并包含重试指引。

请求头行为（精确）

情况返回的请求头
普通认证响应（2xx/4xx，如 422）X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
429 rate_limit_exceeded（日/月额度）X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After
429 rps_limit_exceeded / 429 abuse_penalty_activeRetry-After（RPS 专用 JSON 字段位于响应体中）
重放的幂等响应Idempotency-Replayed: true

429 错误类型

error含义处理方式
rps_limit_exceeded超过每秒请求限制。遵守 Retry-After，并使用带随机抖动的退避重试。响应体可能包含 retry_after_ms、backoff_hint、tier_rps_limit、penalty_active。
abuse_penalty_active重复突发请求后进入临时惩罚窗口。不要密集重试，等待完整惩罚窗口结束。
rate_limit_exceeded达到当前套餐的日/月额度。等待额度重置或升级套餐。
idempotency_key_reused同一个 Idempotency-Key 被用于不同 method、path、query 或 body。为新的操作生成新 key。HTTP status 是 409。
request_in_progress同 key 的匹配请求仍在执行中。等待 Retry-After 后，用相同 key 重试完全相同的请求。HTTP status 是 409。

使用 Idempotency-Key 安全重试

经过认证且可能计费的 POST 请求支持可选请求头 Idempotency-Key: <client-generated unique operation key>。当你重试可能已经到达 API 后发生超时的请求时使用它。

如果方法、path、query string、body 和 key 完全相同，重放请求会返回第一次完成的响应，并包含 Idempotency-Replayed: true。重放不会重新计算，也不会额外消耗额度。

key 通常保留约 24 小时。不带该请求头的请求行为保持不变。

推荐客户端重试策略

  1. 只要响应包含 Retry-After，就优先遵守它。
  2. 使用指数退避和完整随机抖动。
  3. 建议基础延迟：250ms，最大延迟：5s。
  4. 对计费 POST 重试，只在完全相同请求上复用同一个 Idempotency-Key。
  5. 设置重试上限，避免无限重试。

重要注意事项

  • 收到 429 后不要立即在紧密循环中重试。
  • 重复突发请求可能触发临时阻断窗口。
  • 即使客户端做了限流，服务端限制仍会被执行。

参考

Base URL: https://api.freeastroapi.com

本页面是限流响应在 docs 字段中返回的目标页面。