速率限制与约定

有几项约定适用于整个 API。提前了解它们，能让你在使用每一个接口时都少踩坑，因此这些内容放在这里统一说明，而不是在参考文档中反复重复。

速率限制

• 每个已登录用户的请求限制为每分钟 60 次。
• POST /api/register 和 POST /api/login 限制为每分钟 6 次，用于防止撞库攻击。

超出限制时，API 会返回 HTTP 429。请稍等片刻后再重试。如果你在编写批量导入脚本，请控制请求节奏，而不是尽可能快地连续发送，同时请记住 API 每个请求只处理一个对象，没有批量接口。

分页

列表接口都是分页的，并共享同一套信封结构：

• data 存放当前页的资源。
• links 存放 first、last、prev 和 next 链接。
• meta 存放当前页码、总数以及相关信息。

每页默认包含10 条资源。可以通过 per_page 查询参数请求更多，最多100 条。持续跟随 links.next 直到其为 null，即可遍历整份列表。

金额以最小货币单位表示

API 中的每一个金额（估计价值、交易金额、押金、投保价值）都是以其货币最小单位表示的整数。对于美元和欧元来说，这意味着以"分"为单位：一笔 49.99 美元的购买会以 4999 传输。这样可以完全避免浮点数舍入问题。请在你自己的代码中将其转换为可读格式，并记住每个收藏都有自己的货币单位。

无权限的请求会返回"未找到"

API 遵循与网页应用相同的角色规则，但有一处刻意的差异：如果你无权执行某个操作，或者请求的资源属于其他账户，接口会返回404 未找到，而不是 403 禁止访问。调用方无法分辨"这个资源不存在"和"这个资源不属于你"这两种情况，因为 API 从不确认你账户之外是否存在某个资源。

错误与校验

校验失败时会返回 HTTP 422，附带一个 message 字段和一个以字段名为键的 errors 对象。其他错误遵循常规的 HTTP 语义：令牌缺失或已被撤销时返回 401，如上文所述返回 404，触发速率限制时返回 429。

接下来去哪里

• 在 /docs/api 的自动生成参考文档中查看这些约定在真实接口上的实际应用。
• 想了解事件推送的未来计划？阅读 Webhook 当前的进展情况。