エラーと制限
共通のエラー形式、すべてのエラーコード、リクエストID、プランごとのリクエスト制限、検索と件数確認の制限、1日の上限、ページ送り、安全な再試行について説明します。
共通のエラー形式
エラーの応答はすべて同じ形をしています。error.codeを読んで対応を決め、利用者にはerror.messageを表示してください。メッセージはわかりやすい1文です。
{
"error": {
"code": "insufficient_credits",
"message": "Revealing these people costs 1 credit each and the account has none left. Pick a plan at https://argorant.com/pricing.",
"details": { "needed": 25, "balance": 0 }
},
"request_id": "req_8f2c1d9e0b7a4c3e9f1a2b3c4d5e6f70",
"detail": "..."
}detailには、この形式より前に作られたクライアント向けに、以前の形式のエラーが入っています。新しいコードではerrorを読んでください。
エラーコード
| コード | ステータス | 意味と対処 |
|---|---|---|
invalid_request | 400 | リクエストに不足があるか、値が正しくありません。メッセージに修正点が書かれています。 |
launch_blocked | 400 | キャンペーンはまだ開始できません。details.blockersに不足しているものが一覧表示されます。 |
unauthorized | 401 | APIキーがないか、キーが間違っているか、取り消されています。 |
api_key_required | 401 | このルートには、ブラウザのセッションではなく、APIキーまたはコネクタでのログインが必要です。 |
plan_required | 402 | アカウントのプランにこの機能は含まれていません。メッセージに、この機能を含むプランが示されます。プランもクレジットもないアカウントのキーは、すべての呼び出しでこのコードを受け取ります。 |
insufficient_credits | 402 | この呼び出しに必要なクレジットが足りません。必要な数はdetailsに示されます。料金は発生していません。 |
scope_missing | 403 | この呼び出しに必要なスコープがキーにありません。そのスコープを持つキーを作成してください。 |
permission_missing | 403 | ワークスペースでのあなたの役割では、この操作は許可されていません。 |
forbidden | 403 | このアカウントでは、この操作は許可されていません。 |
not_found | 404 | ワークスペースにその項目はありません。ほかのワークスペースの項目にも同じ応答を返します。 |
route_not_found | 404 | そのエンドポイントはありません。パスをリファレンスと照らし合わせてください。 |
method_not_allowed | 405 | パスは存在しますが、このHTTPメソッドでは使えません。使えるメソッドはdetails.allowedに一覧表示されます。 |
conflict | 409 | 項目がこの操作を許可しない状態にあります。たとえば、実行中のキャンペーンの削除などです。 |
idempotency_conflict | 409 | このIdempotency-Keyは、別のボディですでに使われています。 |
idempotency_in_progress | 409 | このIdempotency-Keyのリクエストはまだ実行中です。少し待ってから再試行してください。 |
gone | 410 | 項目の期限が切れています。たとえば、保存期間を過ぎたエクスポートファイルです。 |
quote_expired | 410 | 見積もりが古すぎます。新しい見積もりを取得して、もう一度確定してください。 |
validation_error | 422 | 項目の型が間違っているか、項目が不足しています。各問題はdetails.fieldsに一覧表示されます。 |
access_key_activation_required | 428 | この招待アクセスキーはまだ有効になっていません。先にdetails.claim_urlでメールアドレスを確認してください。 |
rate_limited | 429 | この1分間または10秒間のリクエスト、この1分間の検索と件数確認が多すぎるか、1分間に表示した人物が200人を超えました。Retry-Afterの秒数だけ待ってください。 |
daily_limit_reached | 429 | 1日の上限に達しました。この種類の呼び出しに対するキーの上限か、プランのないアカウントの1日あたりの新しいメールアドレス数の上限です。どちらかはdetails.actionに示されます。上限はUTCの午前0時にリセットされます。 |
internal_error | 500 | こちら側で問題が発生しました。再試行してください。失敗が続く場合は、リクエストIDを添えてお問い合わせください。 |
unavailable | 503 | サービスの一部が混雑しているか、一時停止しています。1分後に再試行してください。 |
confirmation_required | 400 | 注文にはconfirmed=trueが必要です。支払う人が承認した後にだけ送信してください。 |
invalid_webhook_url | 400 | Webhookのアドレスは、公開されているhttps://のアドレスである必要があります。 |
invalid_webhook_events | 400 | イベント名が不明か、イベントが指定されていません。不明な名前はdetails.invalidに一覧表示されます。 |
webhook_limit_reached | 400 | オンになっているWebhookが10件、またはオフのものを含めて合計50件あります。先に1件削除するか、オフにしてください。チームメンバーはそれぞれ自分の枠を持っています。 |
event_not_subscribed | 400 | テスト呼び出しで、Webhookが受け取らないイベントが指定されました。受け取るイベントはdetails.eventsに一覧表示されます。 |
company_credits_required | 402 | 企業の完全なプロフィールにはクレジットがかかりますが、アカウントのクレジットが足りません。無料部分はdetails.teaserに入っています。料金は発生していません。 |
search_busy | 503 | 現在、検索が混雑しています。数秒後にもう一度お試しください。 |
phones_not_in_plan | 402 | 電話番号はProプランから使えます。料金は発生していません。 |
card_not_charged | 402 | 保存されたカードには請求されませんでした。何も購入されていません。代わりに支払いリンクから支払ってください。 |
owner_only | 403 | この操作はワークスペースのオーナーだけが行えます。たとえば、メールボックスの注文や解約です。 |
quote_not_found | 404 | 見積もりが存在しないか、ほかの人のものです。新しい見積もりを取得してください。 |
charge_in_progress | 409 | この見積もりは現在請求処理中です。少し後で注文を確認してください。 |
not_enough_names | 409 | 空いているドメイン名が十分に見つかりませんでした。ドメインをいくつかご自身で送ってください。 |
not_paid | 409 | 注文はまだ支払われていないため、解約するものがありません。 |
reason_required | 422 | メールボックスの解約には、一覧の選択肢から選んだ理由が必要です。 |
not_connected | 409 | そのツールはまだ接続されていません。先に「設定」の「接続済みのツール」で接続してください。 |
unsupported_tool | 409 | この接続済みのツールは、人物を直接受け取れません。代わりに「エクスポート」ページからエクスポートを送ってください。 |
tool_key_rejected | 409 | 接続済みのツールが、保存されたキーを受け付けませんでした。「設定」の「接続済みのツール」でもう一度接続してください。 |
price_mismatch | 409 | 相手に示した料金が、見積もりの料金と一致しません。見積もりの料金を示して、もう一度確認してください。 |
quote_other_session | 409 | 見積もりは別のキーまたは接続で作成されました。ここで新しい見積もりを依頼し、もう一度確定してください。 |
export_failed | 409 | エクスポートが完了しなかったため、送るものがありません。エクスポートをもう一度実行してください。 |
sign_in_failed | 422 | メールサーバーがログインを受け付けなかったため、メールボックスは接続されませんでした。送信と返信の読み取りそれぞれで何が問題だったかは、details.testに示されます。 |
campaign_not_started | 409 | キャンペーンは下書きのため、一時停止するものがありません。先に開始してください。 |
finder_rate_limit | 429 | この1分間のメールアドレス検索(1件ずつ)が30回を超えました。Retry-Afterの秒数だけ待ってください。 |
finder_daily_limit | 429 | 今日のメールアドレス検索が2,000回に達しました。上限はUTCの午前0時にリセットされます。 |
finder_miss_rate_throttle | 429 | 最近の検索のほとんどで何も見つからなかったため、しばらくの間、検索は1時間20回に抑えられます。氏名とドメインを確認してください。 |
confirmation_requiredやquote_not_foundのように、独自のコードを追加する操作もあります。各操作のコードはリファレンスに記載されています。知らないコードは、そのHTTPステータスに従って扱ってください。
リクエストID
すべての応答にはX-Request-Idヘッダーが付き、すべてのエラーはそれをrequest_idとして繰り返します。自分のログで呼び出しを探せるよう、独自のIDをX-Request-Idヘッダーで送ることもできます(英字、数字、ドット、ハイフン、アンダースコアで8~64文字)。サポートに問い合わせる際は、このIDを伝えてください。
1分あたりのリクエスト数
各キーが1分間に送れるリクエスト数は以下のとおりで、任意の10秒間では2列目の数までです。
| プラン | 1分あたりのリクエスト数 | 10秒間 |
|---|---|---|
| プランなし、APIキーまたはCLI | 30 | 15 |
| プランなし、AIアシスタント | 60 | 20 |
| Starter | 60 | 15 |
| Pro | 240 | 60 |
| Scale | 600 | 150 |
| Hyperscale | 1,200 | 300 |
「プランなし」には、まだプランを選んでいないアカウントの最初の7日間と、以前に購入したクレジットを使うアカウントが含まれます。プランのトライアル中は、そのプランの制限が適用されます。プランもクレジットもないアカウントのキーは、GET /api/v1/accountを含むすべての呼び出しで402 plan_requiredを受け取ります。
キーによる呼び出しの応答にはすべて、X-RateLimit-Limit(1分あたりのリクエスト数)、X-RateLimit-Remaining(この1分間に残っているリクエスト数)、X-RateLimit-Reset(次の1分が始まるまでの秒数)が付きます。どちらかの制限を超えると、Retry-Afterヘッダー付きの429 rate_limitedが返ります。その秒数だけ待ってから、もう一度お試しください。
人物の表示には、すべてのプランでもう1つ制限があります。1つのアカウントが1分間に表示できるのは200人までです。これを超えた場合も429 rate_limitedが返ります。
検索と件数確認
検索、件数確認、プレビューは無料です。制限はアカウント単位で、すべてのキーとコネクタに共通なので、キーを増やしても枠は増えません。
| プラン | 1分あたり | 1日の件数確認 | 1日のプレビュー行数 |
|---|---|---|---|
| プランなし、APIキーまたはCLI | 10 | 500 | 500 |
| プランなし、AIアシスタント | 20 | 1,000 | 1,000 |
| Starter | 30 | 上限なし | 上限なし |
| Pro | 60 | 上限なし | 上限なし |
| Scale | 90 | 上限なし | 上限なし |
| Hyperscale | 120 | 上限なし | 上限なし |
プランがない場合、検索と件数確認の応答にはX-RateLimit-Daily-LimitとX-RateLimit-Daily-Remainingも付きます。プレビューは1回の呼び出しで最大10人です。
キーごとの1日の上限
プランがない場合、各キーには1日の上限もあります。プラン利用中に1日の上限があるのはメールアドレス検索だけで、それ以外はクレジットの範囲内で使えます。1日の上限はUTCの午前0時にリセットされます。今日の残りはGET /api/v1/accountで確認できます。
| 対象 | 1日あたり | 1回の呼び出しあたり |
|---|---|---|
| フィルターによる人物の表示 | 100(プラン利用中は上限なし) | 25 |
| エクスポートの行数 | 50,000(プラン利用中は上限なし) | 1ファイル50,000、1バッチ500,000 |
| メールアドレス検索 | 2,000 | 1分あたり30、リストは最大10,000行 |
プランのないアカウントが見つけられる新しいメールアドレスは、合計で1日10件までです。表示、メールアドレス検索の結果、エクスポートの行はまとめて数えられ、以前に取得したメールアドレスは数えられません。
1日の上限を超えると、429 daily_limit_reachedが返ります。1日の表示上限より多くの人物が必要な場合は、リストを保存するか、エクスポートするか、キャンペーンに追加してください。これらの方法は数千人規模を想定しています。メールアドレス検索は独自のコードで応答します。finder_rate_limit(1分あたり)、finder_daily_limit(1日あたり)、finder_miss_rate_throttle(ほとんどの検索で何も見つからなかった場合)です。
ページ送り
一覧系の操作はすべてlimitとcursorを受け取ります。応答は独自のキー(たとえばcampaignsやpeople)を保ったまま、total、limit、offset、next_cursor、has_moreを追加します。次のページを取得するには、next_cursorをcursorとして渡します。最後のページではnullになります。行数を自分で数えたい場合は、offsetも使えます。
途中で終わる一覧や、独自の方法でページ送りする一覧もあります。キャンペーン内の人物は、afterにnext_afterを設定して固定の順序でページ送りし、それらのページにはnext_cursorが付きません。キャンペーンの返信も同じくafterとnext_afterでページ送りします。キャンペーンの一覧で取得できるのは最初の500件で、cursorはその範囲内でページ送りします。受信トレイ、キャンペーンの返信、キャンペーン内の人物は、ISO 8601形式の日付フィルター(updated_afterとreceived_after、またはcreated_after)も受け付けます。
curl "https://app.argorant.com/api/v1/campaigns?limit=25" -H "Authorization: Bearer $ARGORANT_API_KEY"
curl "https://app.argorant.com/api/v1/campaigns?limit=25&cursor=bzoyNQ" -H "Authorization: Bearer $ARGORANT_API_KEY"total_is_estimateがtrueのとき、totalは少なくともその数があることを示します。たとえば、リストが最大サイズに達した場合です。
安全な再試行
作成、変更、削除、返信、転送、クレジットや料金がかかる操作など、すべての書き込みでIdempotency-Keyヘッダーを送ってください。新しい操作には毎回新しいランダムな値を使い、再試行するときは同じ値を使います。
- 24時間以内に同じキーと同じボディを送ると、最初の応答が
Idempotent-Replayed: trueヘッダー付きで返ります。処理が二重に行われることはありません。 - 同じキーで別のボディを送ると、
409 idempotency_conflictが返ります。 - 最初のリクエストがまだ実行中のときに再試行すると、
409 idempotency_in_progressが返ります。少し待ってから、もう一度お試しください。 - エラーは保存されないため、問題を修正して同じキーで再試行できます。
curl -X POST "https://app.argorant.com/api/v1/exports" \
-H "Authorization: Bearer $ARGORANT_API_KEY" \
-H "Idempotency-Key: export-cfo-germany-2026-10-07" \
-H "Content-Type: application/json" \
-d '{"filters":{"title":"CFO","country":"Germany"},"limit":500}'開始できないキャンペーン
POST /api/v1/campaigns/{id}/launchは、メール、今日の送信枠が残っているメールボックス、人物など、何かが不足している間はlaunch_blockedを返します。details.blockersには、不足しているものが1つずつわかりやすい言葉で一覧表示されます。GET /api/v1/campaigns/{id}も同じ一覧をlaunch_blockersとして表示するので、開始を試す前に修正できます。