速率限制与配额
限流按密钥摘要与 IP 双维度全局计数。www 与 api 两个入口主机合计计数，不会各算一份。
60/分钟密钥维度每分钟请求数
10 000/天密钥维度每日请求数
600/分钟IP 维度每分钟请求数
| 响应头 | 含义 |
|---|---|
| RateLimit-Scope | 本次计数维度（apikey / ip） |
| RateLimit-Limit | 窗口内允许的请求数 |
| RateLimit-Window-Seconds | 窗口长度（秒） |
| RateLimit-Retry-After | 被限流时建议的等待秒数 |
超出配额
返回 429 rate_limited，响应体带 retry_after 秒数。请以指数退避重试，不要在客户端固定间隔猛轮询。实时用量可调 /api/v1/usage。
cursor-page/1 分页契约
所有列表端点（orders / invoices / submissions）使用同一种分页结构。快照时间戳随响应返回，保证翻页期间数据一致。
# 第一页
curl https://api.quickfindapp.com/api/v1/orders?limit=50 \
-H "Authorization: Bearer qf_live_xxxxxxxx"
# 响应（节选）
{
"ok": true,
"contract": "cursor-page/1",
"resource": "orders",
"limit": 50,
"count": 50,
"has_more": true,
"next_cursor": "eyJ…",
"snapshot_at": "2026-10-16T09:00:00.000Z",
"orders": [ … ]
}| 字段 | 含义 |
|---|---|
| limit | 本次生效的每页条数（默认 50、上限 200） |
| count | 本页实际返回条数 |
| has_more | 是否还有下一页 |
| next_cursor | 下一页游标；末页为 null |
| snapshot_at | 快照时间，同一游标序列内数据一致 |
翻页守则
has_more 为 true 时，把 next_cursor 原样作为 cursor 参数请求下一页；next_cursor 为 null 即末页。游标是不透明字符串，勿解析或拼接。
幂等写入
所有 POST 请求建议携带 Idempotency-Key 头。网络超时后重试，使用同一个 Key 不会产生重复副作用。
| 场景 | 结果 |
|---|---|
| 同一 Key + 同一请求体，首次请求 | 正常执行并记录响应 |
| 同一 Key + 同一请求体，重试 | 直接回放首次响应（不重复执行） |
| 同一 Key + 不同请求体 | 409 idempotency_conflict |
| 同一 Key，首次请求仍在处理 | 409 idempotency_in_progress，稍后重试 |
| 未携带 Idempotency-Key | 响应带 X-QF-Idempotency: not_supplied，仍可正常执行 |
Key 建议使用业务自然键（如你的订单号 + 操作类型），长度上限 200 字符；同一 Key 的处理结果保留有限时间，超时后按新请求处理。
curl -X POST https://api.quickfindapp.com/api/v1/webhooks \
-H "Authorization: Bearer qf_live_xxxxxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: my-app-wh-0001" \
-d '{"url":"https://example.com/hook","events":["order.paid"]}'