限制
你可以发出多少请求。
每分钟请求数
每个端点每分钟允许固定数量的请求。对于数据端点和读取账户，一个账户的所有密钥和令牌合并计算。每个请求都计数，被拒绝的也一样。
| 端点 | 内容 | 每分钟限制 |
|---|---|---|
| fetch-organization | 公司档案 | 60 |
| fetch-person | 人物档案 | 60 |
| search-organizations | 搜索与导出 | 60 |
| fetch-document | 文件 | 5 |
| signals | Signals | 60 |
| account | 读取账户 | 30 |
| account, auth/tokens | 管理 Bearer 令牌；创建、更新和删除密钥、监控和 Webhook 端点 | 10 |
| account/webhook-endpoints | 验证和测试 Webhook 端点，轮换密钥 | 6 |
搜索、文件和 Signals 共用每分钟 60 次请求的配额。文件还有自己更小的限制。
对账户、监控和 Webhook 的写请求也计入账户限制。 每个端点页面的“费用和限制”下都列有相同的数字。
所有积分订阅的限制都相同。如果你需要每分钟更多请求，Enterprise 合同可以为你提供更高的限制。
达到限制
超出限制时，API 返回 429。请求头 Retry-After 告诉你多少秒后可以再次发送请求。字段 retry_after 中有相同的数字。
每个响应都在请求头中显示你还剩多少余量：
| 请求头 | 含义 | 示例 |
|---|---|---|
| X-RateLimit-Limit | 该端点每分钟的限制。 |
30 |
| X-RateLimit-Remaining | 本分钟内还可以发出多少请求。 |
0 |
| Retry-After |
仅在 429 时：距离下一次可发请求的秒数。
|
17 |
| X-RateLimit-Reset |
仅在 429 时：可以继续的时间，Unix 时间。
|
1793519682 |
1{2 "error": "Too many requests",3 "message": "Rate limit exceeded. Retry after 17 seconds.",4 "retry_after": 175}
发送大量请求时，请留意 X-RateLimit-Remaining，在 API 返回 429 之前自行放慢速度。超出限制的请求不收费。
超时
大多数响应在几秒内到达。AI 模式、功能 news、实时获取、fetch-person 和文件耗时更长，因为我们直接从登记册获取文件和实时数据。
请将客户端的超时设置为至少 120 秒，尤其是实时模式、fetch-person 和文件。超时太短会中止即将完成的请求。
文件还可以使用 async=true：API 立即以 202 响应，并在后台获取文件，见 fetch-document。
408，文件为带 Retry-After 的 504。不收费。请稍后重试。如果只是实时模式的实时获取失败，你会得到含已存储数据的公司档案，不收取实时模式附加费。
重试而不重复计费
如果你的客户端中止了请求，它在我们这边仍可能完成并计费。使用请求头 Idempotency-Key，重试就不收费。
为每个请求选择一个单独的键，并在重试时原样发送。键由 1 至 128 个字符组成：字母、数字、句点、下划线、冒号和连字符，以字母或数字开头。
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: YOUR_API_KEY" \ -H "Idempotency-Key: hetzner-profile-2026-11-01" \ --data-urlencode "q=Ansbach HRB 6089"
| 情况 | 数据端点 | 监控和 Webhook |
|---|---|---|
| 是否必须提供键 | 否，可选 |
是，否则返回 428
|
| 时间窗口 | 24 小时 | 24 小时 |
| 相同的键，相同的参数 | 再次返回结果，不计费 | 已存储的响应及其状态 |
| 相同的键，不同的参数 |
422 idempotency_key_reused |
409 idempotency_conflict |
| 出错后 | 键仍可使用 | 返回相同的错误，需要新键 |
数据端点
fetch-organization、fetch-person、search-organizations 和 fetch-document 可选择接受该键。如果你在 24 小时内用相同的键和相同的参数重复请求，你会再次得到结果，且不计费。
第一个响应带有请求头 Idempotency-Status: created，每次重试带有 Idempotency-Status: replayed 和 meta.request_credit_cost: 0。重试不需要余额。
只有交付的结果才会绑定该键。因此出错后你可以继续使用同一个键。相同的键配不同的参数会返回带 idempotency_key_reused 的 422。数据端点会忽略其他格式的键，因此请严格遵守格式。
signals 不接受幂等键。
1{2 "error": "idempotency_key_reused",3 "message": "This Idempotency-Key was already used with different parameters.",4 "meta": {5 "request_credit_cost": 0,6 "credits_remaining": 1457 }8}
监控和 Webhook
对 /v1/account/monitors、/v1/account/webhook-endpoints 和 /v1/account/webhook-deliveries 的写请求需要该键。没有时，API 返回 428；格式错误的键返回 400。
在 24 小时内，相同的键和相同的参数会返回已存储的响应及其状态，另加 Idempotency-Status: replayed。这也适用于错误。因此对于新的尝试（例如再次验证），你需要使用新键。
相同的键配不同的参数会返回带 idempotency_conflict 的 409。如果第一个请求仍在运行，你会收到带 idempotency_in_progress 的 409。
规划你的重试
并非每个错误都值得再试一次。处理方法如下：
- 重试：
408、按Retry-After等待后的429，以及5xx。每次尝试之间等待更久，例如 2、4、8 秒，几次尝试后停止。 - 先修正，再发送：
400、401、402、403、404和422。再次发送相同的请求会得到相同的结果。 - 为付费请求发送幂等键。这样中止后的重试就不收费。