# 速率限制与约定

有几项约定适用于整个 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` 传输。这样可以完全避免浮点数舍入问题。请在你自己的代码中将其转换为可读格式，并记住每个[收藏](https://getkollek.com/zh/docs/hexin-gainian/shoucang)都有自己的货币单位。

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

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

:::note
如果某个接口对一个你在应用中明明能看到的对象意外返回了 404，请检查你所使用令牌对应用户的角色。查看者的令牌在任何写操作上都会得到 404。
:::

## 错误与校验

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

## 接下来去哪里

- 在 `/docs/api` 的自动生成参考文档中查看这些约定在真实接口上的实际应用。
- 想了解事件推送的未来计划？阅读 [Webhook](https://getkollek.com/zh/docs/kaifazhe-yu-api/webhook) 当前的进展情况。