错误与限制

管理错误包含 error（可读文本）和 code（稳定值）。请根据 code 和 HTTP 状态码分支处理，而不是根据消息文本。Scope 错误可能包含 required 和 missing_scope；可重试的响应可能包含 retryAfter、retryable 和 Retry-After。所有权校验失败返回 404，以避免泄露其他钱包的资源。

{ "error": "Insufficient scope", "code": "insufficient_scope", "required": "write" }

• 400：无效的 JSON、无效的请求或被拒绝的目标。
• 401：缺失/无效的认证或被拒绝的签名。
• 402：Credits 不足或需要 Slot 容量。
• 403：Scope 不足或其他明确的权限限制。
• 404：资源不存在或属于他人。
• 409：冲突、活跃的幂等租约、重复使用的 key 或已暂停的资产。
• 410：充值草稿已过期。
• 422：付款验证失败。
• 429：速率限制或安全回退容量耗尽。
• 503：价格、Signer 不可用或临时依赖故障。

遵守 Retry-After，使用带抖动的指数退避和有限的尝试次数。使用相同的 key 和请求体重复幂等操作。不要盲目重试认证失败或被拒绝的权限。切勿仅因第一次响应超时就购买第二份订阅。只有在现有指令不再可用时才刷新报价或草稿。

Challenge 和 Token 兑换限制为每 IP 每分钟 30 次请求。充值草稿、订阅购买和创建 Watch 限制为每钱包每分钟 10 次。Watch 的 PATCH/DELETE 允许每分钟 60 次；设置 PUT 和消息预览允许每分钟 30 次；告警导出允许每小时 10 次。限制在幂等处理之前生效，包括重放。Redis 不可用时使用有界的进程内回退；回退容量耗尽时，安全限制会拒绝请求而非放开。

创建收件人和更改目标共享每钱包每小时 10 次。确认邮件有按钱包和按规范化目标的预算。被限流的重发可能返回 HTTP 200 并带有 sent: false，而不是 429；请检查该字段。创建收件人可能报告 confirmationSent: false。待处理的目标保持未验证状态，不能接收测试或告警。

账户 Ledger 和 Watch 列表接受 limit 和一个不透明的 cursor。跟随 nextCursor 直到 null；不要解释或修改 Cursor。告警历史改用从零开始的 page 和 pageSize，并支持筛选和排序。导出限制为 5,000 行。不要混用这两种分页模型。

curl 'https://ftso.app/api/x402/watches?limit=20' \
  -H 'authorization: Bearer fbx_READ_TOKEN'
# Follow the returned nextCursor, URL-encoded, on the next request.

完整的稳定错误码枚举发布在 OpenAPI 文档中。权限参见操作参考。