ArgorantDocs

エラーと制限

共通のエラー形式、すべてのエラーコード、リクエストID、プランごとのリクエスト制限、検索と件数確認の制限、1日の上限、ページ送り、安全な再試行について説明します。

共通のエラー形式

エラーの応答はすべて同じ形をしています。error.codeを読んで対応を決め、利用者にはerror.messageを表示してください。メッセージはわかりやすい1文です。

JSON
{
  "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_request400リクエストに不足があるか、値が正しくありません。メッセージに修正点が書かれています。
launch_blocked400キャンペーンはまだ開始できません。details.blockersに不足しているものが一覧表示されます。
unauthorized401APIキーがないか、キーが間違っているか、取り消されています。
api_key_required401このルートには、ブラウザのセッションではなく、APIキーまたはコネクタでのログインが必要です。
plan_required402アカウントのプランにこの機能は含まれていません。メッセージに、この機能を含むプランが示されます。プランもクレジットもないアカウントのキーは、すべての呼び出しでこのコードを受け取ります。
insufficient_credits402この呼び出しに必要なクレジットが足りません。必要な数はdetailsに示されます。料金は発生していません。
scope_missing403この呼び出しに必要なスコープがキーにありません。そのスコープを持つキーを作成してください。
permission_missing403ワークスペースでのあなたの役割では、この操作は許可されていません。
forbidden403このアカウントでは、この操作は許可されていません。
not_found404ワークスペースにその項目はありません。ほかのワークスペースの項目にも同じ応答を返します。
route_not_found404そのエンドポイントはありません。パスをリファレンスと照らし合わせてください。
method_not_allowed405パスは存在しますが、このHTTPメソッドでは使えません。使えるメソッドはdetails.allowedに一覧表示されます。
conflict409項目がこの操作を許可しない状態にあります。たとえば、実行中のキャンペーンの削除などです。
idempotency_conflict409このIdempotency-Keyは、別のボディですでに使われています。
idempotency_in_progress409このIdempotency-Keyのリクエストはまだ実行中です。少し待ってから再試行してください。
gone410項目の期限が切れています。たとえば、保存期間を過ぎたエクスポートファイルです。
quote_expired410見積もりが古すぎます。新しい見積もりを取得して、もう一度確定してください。
validation_error422項目の型が間違っているか、項目が不足しています。各問題はdetails.fieldsに一覧表示されます。
access_key_activation_required428この招待アクセスキーはまだ有効になっていません。先にdetails.claim_urlでメールアドレスを確認してください。
rate_limited429この1分間または10秒間のリクエスト、この1分間の検索と件数確認が多すぎるか、1分間に表示した人物が200人を超えました。Retry-Afterの秒数だけ待ってください。
daily_limit_reached4291日の上限に達しました。この種類の呼び出しに対するキーの上限か、プランのないアカウントの1日あたりの新しいメールアドレス数の上限です。どちらかはdetails.actionに示されます。上限はUTCの午前0時にリセットされます。
internal_error500こちら側で問題が発生しました。再試行してください。失敗が続く場合は、リクエストIDを添えてお問い合わせください。
unavailable503サービスの一部が混雑しているか、一時停止しています。1分後に再試行してください。
confirmation_required400注文にはconfirmed=trueが必要です。支払う人が承認した後にだけ送信してください。
invalid_webhook_url400Webhookのアドレスは、公開されているhttps://のアドレスである必要があります。
invalid_webhook_events400イベント名が不明か、イベントが指定されていません。不明な名前はdetails.invalidに一覧表示されます。
webhook_limit_reached400オンになっているWebhookが10件、またはオフのものを含めて合計50件あります。先に1件削除するか、オフにしてください。チームメンバーはそれぞれ自分の枠を持っています。
event_not_subscribed400テスト呼び出しで、Webhookが受け取らないイベントが指定されました。受け取るイベントはdetails.eventsに一覧表示されます。
company_credits_required402企業の完全なプロフィールにはクレジットがかかりますが、アカウントのクレジットが足りません。無料部分はdetails.teaserに入っています。料金は発生していません。
search_busy503現在、検索が混雑しています。数秒後にもう一度お試しください。
phones_not_in_plan402電話番号はProプランから使えます。料金は発生していません。
card_not_charged402保存されたカードには請求されませんでした。何も購入されていません。代わりに支払いリンクから支払ってください。
owner_only403この操作はワークスペースのオーナーだけが行えます。たとえば、メールボックスの注文や解約です。
quote_not_found404見積もりが存在しないか、ほかの人のものです。新しい見積もりを取得してください。
charge_in_progress409この見積もりは現在請求処理中です。少し後で注文を確認してください。
not_enough_names409空いているドメイン名が十分に見つかりませんでした。ドメインをいくつかご自身で送ってください。
not_paid409注文はまだ支払われていないため、解約するものがありません。
reason_required422メールボックスの解約には、一覧の選択肢から選んだ理由が必要です。
not_connected409そのツールはまだ接続されていません。先に「設定」の「接続済みのツール」で接続してください。
unsupported_tool409この接続済みのツールは、人物を直接受け取れません。代わりに「エクスポート」ページからエクスポートを送ってください。
tool_key_rejected409接続済みのツールが、保存されたキーを受け付けませんでした。「設定」の「接続済みのツール」でもう一度接続してください。
price_mismatch409相手に示した料金が、見積もりの料金と一致しません。見積もりの料金を示して、もう一度確認してください。
quote_other_session409見積もりは別のキーまたは接続で作成されました。ここで新しい見積もりを依頼し、もう一度確定してください。
export_failed409エクスポートが完了しなかったため、送るものがありません。エクスポートをもう一度実行してください。
sign_in_failed422メールサーバーがログインを受け付けなかったため、メールボックスは接続されませんでした。送信と返信の読み取りそれぞれで何が問題だったかは、details.testに示されます。
campaign_not_started409キャンペーンは下書きのため、一時停止するものがありません。先に開始してください。
finder_rate_limit429この1分間のメールアドレス検索(1件ずつ)が30回を超えました。Retry-Afterの秒数だけ待ってください。
finder_daily_limit429今日のメールアドレス検索が2,000回に達しました。上限はUTCの午前0時にリセットされます。
finder_miss_rate_throttle429最近の検索のほとんどで何も見つからなかったため、しばらくの間、検索は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キーまたはCLI3015
プランなし、AIアシスタント6020
Starter6015
Pro24060
Scale600150
Hyperscale1,200300

「プランなし」には、まだプランを選んでいないアカウントの最初の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キーまたはCLI10500500
プランなし、AIアシスタント201,0001,000
Starter30上限なし上限なし
Pro60上限なし上限なし
Scale90上限なし上限なし
Hyperscale120上限なし上限なし

プランがない場合、検索と件数確認の応答には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,0001分あたり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)も受け付けます。

Shell
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が返ります。少し待ってから、もう一度お試しください。
  • エラーは保存されないため、問題を修正して同じキーで再試行できます。
Shell
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として表示するので、開始を試す前に修正できます。

このページの内容