跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.qoder.com/llms.txt

Use this file to discover all available pages before exploring further.

Qoder Cloud Agents API 当前在应用层 暂无自行限流机制。请求频率由网关层面的全局保护策略管控。

​
当前状态

层面限流策略说明
API 应用层暂无不主动返回 429 Too Many Requests
网关层有全局保护，防止异常流量冲击
虽然 API 层暂无显式限流，但这并不意味着可以无限制地发送请求。网关层仍会在异常流量下进行拦截保护。

​
网关层面保护

网关层提供以下保护能力：
  1. 突发流量抑制 — 短时间内大量请求可能被暂时拦截
  2. 连接数限制 — 单客户端并发连接数有上限
  3. DDoS 防护 — 自动识别并阻断恶意流量
当触发网关保护时，可能收到：
  • HTTP 429 或 503 响应
  • 连接被直接重置（无响应体）

​
推荐的客户端策略

即使没有显式限流，我们仍建议客户端实施自律策略。

​
基本限制建议

操作类型建议频率
读操作（GET）≤ 50 次/秒
写操作（POST/PUT/DELETE）≤ 20 次/秒
批量遍历（分页拉取）每次请求间隔 ≥ 100ms

​
指数退避重试

# 带退避重试的请求示例
max_retries=3
retry_delay=1

for i in $(seq 1 $max_retries); do
  response=$(curl -s -w "\n%{http_code}" \
    "https://openapi.qoder.sh/api/v1/cloud/agents" \
    -H "Authorization: Bearer $QODER_PAT")

  http_code=$(echo "$response" | tail -1)

  # 成功或客户端错误（不需要重试）
  if [ "$http_code" -lt 500 ] && [ "$http_code" != "429" ]; then
    echo "$response" | sed '$d'
    break
  fi

  # 服务端错误或限流，等待后重试
  echo "请求失败 ($http_code)，${retry_delay}s 后重试... ($i/$max_retries)"
  sleep $retry_delay
  retry_delay=$((retry_delay * 2)) # 指数退避
done

​
规划中的限流策略

未来版本将引入正式的限流机制，预期包含：
特性预期行为
速率限制响应头X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset
限流状态码429 Too Many Requests
限流粒度按 PAT / 组织 / 端点分别控制
重试提示Retry-After 响应头
预期响应头格式（规划中）： 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1717200000
Retry-After: 30
建议客户端代码预留对 429 状态码和 Retry-After 头的处理逻辑，以便未来限流上线时无缝适配。

​
批量操作建议

对于需要大量 API 调用的场景： 
# 批量获取多个 Agent 详情（带节流）
agent_ids=("agent_001" "agent_002" "agent_003" "agent_004" "agent_005")

for id in "${agent_ids[@]}"; do
  curl -s "https://openapi.qoder.sh/api/v1/cloud/agents/$id" \
    -H "Authorization: Bearer $QODER_PAT"
  # 请求间隔 200ms，避免触发网关保护
  sleep 0.2
done

​
监控建议

  • 记录每次请求的响应时间，响应变慢可能是接近网关限制的信号
  • 关注 5xx 错误率，突增可能表示已触发保护
  • 实现断路器模式，连续失败时暂停请求