限流与额度
速率限制与月度额度两层限制：全部限流点、429 响应头约定与调用方最佳实践。
CiteArk 的限制分两层：
- 速率限制：防止短时冲击，保护基础设施，按分钟或小时的固定窗口计数；
- 月度额度：管理稀缺资源（算力与存储），按自然月计数。
超出任一层都返回 429，错误形态统一为：
{ "error": "请求过于频繁，请稍后重试" }速率限制
| 接口 | 限制 | 维度 |
|---|---|---|
| 所有携带 API Key 的调用 | 120 次/分钟 | 每把 Key（better-auth 内置） |
POST /api/runs | 10 次/小时 | 账号 |
POST /api/repositories | 5 次/小时 | 账号 |
POST /api/forks | 20 次/小时 | 账号 |
POST /api/stars、/api/requests、/api/follows | 各 60 次/小时 | 账号 |
GET /api/arxiv（元数据查询） | 30 次/小时 | 账号 |
GET /api/arxiv?pdf=1（取 PDF） | 10 次/小时 | 账号 |
POST /api/contact | 5 次/小时 | IP |
POST /api/account/avatar（账号头像） | 10 次/小时 | 账号（仅浏览器会话） |
/api/auth/**（登录/注册等） | 全局 120 次/分钟；登录 10 次/分钟；注册 5 次/分钟；请求重置密码与重发验证邮件各 3 次/分钟 | better-auth 自带限流 |
除 API Key 与 /api/auth/** 的内置限流外，上表限流触发时响应头带：
Retry-After：秒数，精确到当前固定窗口结束；X-RateLimit-Limit：该窗口上限；X-RateLimit-Remaining: 0。
API Key 自带限流触发的 429 只带 Retry-After: 60。
月度额度
| 额度 | 默认上限 |
|---|---|
| 复现运行（run quota） | 每账号每月 10 次 |
| 论文上传 | 每账号每月 25 次，且有字节总量上限（默认 500 MB） |
额度按账号计：浏览器会话与该账号下所有 API Key 共用同一份额度。只有成功进入队列的运行才扣减额度，创建失败会自动返还；上传额度同理，失败返还次数与字节数。当前剩余额度可在 Agent API Key 或 安全与用量 页面查看。
额度耗尽时的 429
月度额度耗尽返回 429（如 { "error": "本月复现额度已用完" }），响应头带：
Retry-After：秒数，指向额度重置时刻；X-Quota-Limit：月度上限；X-Quota-Used：本月已用；X-Quota-Remaining: 0；X-Quota-Reset：重置时间，ISO 格式（UTC，次月 1 日零点）。
调用方最佳实践
- 始终尊重
Retry-After，到点再重试，不要立即重发； - 批量任务加指数退避与随机抖动，避免整队请求同时撞窗口；
- 发起复现前先读一次仓库快照，确认所需 claim 与实验存在且可执行，避免把月度额度浪费在必然失败的请求上；
- 在 Agent API Key 查看每把 Key 的限流窗口用量，在 安全与用量 查看本月额度消耗，快触顶时主动降速。