制限
送信できるリクエストの数。
1分あたりのリクエスト数
各エンドポイントでは、1分あたりのリクエスト数が決まっています。データエンドポイントとアカウントの読み取りでは、アカウントのすべてのキーとトークンが合算されます。拒否されたリクエストも含め、すべてのリクエストがカウントされます。
| エンドポイント | 内容 | 1分あたりの制限 |
|---|---|---|
| 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は1分あたり 60 リクエストの枠を共有します。書類にはさらに独自の、より小さな制限があります。
アカウント、モニタリング、Webhookへの書き込みリクエストは、アカウントの制限にもカウントされます。 同じ数値は、各エンドポイントのページの「コストと制限」にも記載しています。
制限はどのクレジットサブスクリプションでも同じです。1分あたりにもっと多くのリクエストが必要なら、Enterprise契約でより高い制限にできます。
制限に達した場合
制限を超えると、APIは429を返します。ヘッダーRetry-Afterで、何秒後にまたリクエストを送れるかがわかります。同じ数値はフィールドretry_afterにも入ります。
すべてのレスポンスで、残りの余裕がヘッダーに示されます：
| ヘッダー | 意味 | 例 |
|---|---|---|
| X-RateLimit-Limit | このエンドポイントの1分あたりの制限。 |
30 |
| X-RateLimit-Remaining | この1分間にあと何回リクエストできるか。 |
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、書類は時間がかかります。書類とリアルタイムデータは登記簿から直接取得するためです。
特にリアルタイム、fetch-person、書類では、クライアントのタイムアウトを120秒以上に設定してください。タイムアウトが短すぎると、もうすぐ終わるリクエストまで中断してしまいます。
書類には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はIdempotencyキーを受け付けません。
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が返ります。
再試行を計画する
すべてのエラーに2回目の試行が向いているわけではありません。進め方は次のとおりです：
- 再試行する：
408、Retry-After後の429、5xx。試行の間隔は毎回長くし（例えば2秒、4秒、8秒）、数回で止めてください。 - まず修正してから再送する：
400、401、402、403、404、422。同じリクエストをもう一度送っても、同じ結果になります。 - 有料のリクエストにはIdempotencyキーを付けてください。そうすれば、中断後の再試行は無料です。