基本概念

エラー

GemleadはHTTPステータスとJSONのエラーを返します。エラーのtypeとcodeは変わらないので、コードの分岐にそのまま使えます。

エラーオブジェクト

エラーはすべて同じ形式です。messageは人が読むためのもので、変わることがあります。typeとcodeはコードで扱うためのものです。また、エラーかどうかにかかわらず、すべてのレスポンスにRequest-Idヘッダーが付きます。

属性

typestring
エラーの分類。HTTPステータスごとに1つです。
codestring
具体的なエラーの内容。下記のコード一覧を参照してください。
messagestring
エラーを説明する文。
paramstringまたはnull
原因となったパラメーター。該当する場合のみ含まれます。
request_idstring
リクエストのID。Request-Idヘッダーと同じ値です。サポートが必要なときは、このIDをお知らせください。
doc_urlstring
このページで、該当するコードを説明している箇所のURL。

レスポンス400

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "score_min must be an integer from 0 to 100.",
    "param": "score_min",
    "request_id": "req_7Hq2LmX9pT4vK1sN",
    "doc_url": "https://gemlead.ai/docs/errors#parameter_invalid"
  }
}

HTTPステータスコード

ステータス	タイプ	意味
400	`invalid_request_error`	パラメーターが不足している、不明である、または無効です。パスが受け付けないメソッドも、405とともにこのタイプになります。
401	`authentication_error`	キーがない、キーが誤っている、またはキーが無効にされています。
403	`permission_error`	キーは有効ですが、この操作は許可されていません。`read`キーでの書き込みや、FreeプランやStarterプランのアカウントなどです。
404	`not_found_error`	キーのアカウントに該当するオブジェクトがないか、そのルートが存在しません。
409	`idempotency_error`	`Idempotency-Key`が別のリクエストで再利用されたか、最初のリクエストがまだ処理中です。
429	`rate_limit_error`	リクエストが多すぎます。`Retry-After`秒待ってください。
500	`api_error`	Gemlead側で問題が発生しました。まだ利用できないエンドポイントの場合は501になります。あとで同じ`Idempotency-Key`で再試行してください。

エラーコード

コード	ステータス	意味
`api_key_missing`	401	リクエストに`Authorization`ヘッダーも`X-Api-Key`ヘッダーもありません。
`api_key_invalid`	401	一致するキーがありません。`gl_live_`を含め、キー全体をコピーしたか確認してください。
`api_key_revoked`	401	キーはアプリで無効にされています。新しいキーを作成してください。
`token_expired`	401	AIアシスタントのOAuthアクセストークンの有効期限が切れています。アシスタントが自動で更新します。
`insufficient_scope`	403	キーのスコープは`read`ですが、リクエストはデータを変更しようとしています。`write`付きのキーを使ってください。
`plan_required`	403	アカウントのオーナーがFreeプランかStarterプランを利用しています。APIはトライアル中を含め、BusinessとEnterpriseで利用でき、そのどちらかになれば同じキーが再び使えます。
`forbidden`	403	キーのユーザーには、このXアカウントでこの操作をする権限がありません。たとえば、管理者ではないメンバーがチームを変更したり、ペルソナを共有したりする場合です。
`parameter_missing`	400	必須パラメーターがありません。`param`にその名前が入ります。
`parameter_invalid`	400	100を超えるスコアやISO 8601形式でない日付など、APIが受け付けない値のパラメーターがあります。`param`にその名前が入ります。
`parameter_unknown`	400	クエリまたはボディに、このエンドポイントが受け付けないパラメーターがあります。`param`にその名前が入ります。
`body_invalid`	400	ボディが有効なJSONではないか、JSONオブジェクトではありません。
`cursor_invalid`	400	`cursor`がAPIの発行したものではないか、別のフィルター用に発行されたものです。
`idempotency_key_invalid`	400	`Idempotency-Key`が255文字を超えています。
`method_not_allowed`	405	このパスはこのメソッドを受け付けません。受け付けるメソッドは`Allow`ヘッダーに記載されています。
`url_invalid`	400	Webhook URLがHTTPSでない、認証情報を含んでいる、名前解決できない、またはプライベートアドレスを指しています。
`webhook_endpoint_limit_reached`	400	アカウントにはすでに10個のWebhookエンドポイントがあります。先に1つ削除してください。
`resource_already_exists`	400	すでに存在します。ペルソナにこの獲得方法で登録済みのソースや、登録済みのキーワード検索などです。
`limit_reached`	400	上限に達しています。1アカウントあたり100ペルソナ、1ペルソナあたり500件のキーワード検索、ボードの列50個などです。
`seed_source_refused`	400	新しいペルソナの初期ソースとして受け付けられません。投資家、アクセラレーター、メディアのアカウントなどは、買い手につながらないためです。
`x_profile_not_found`	400	このユーザー名には、読み取れるXのプロフィールがありません。
`lead_without_x_id`	400	リードにまだXアカウントIDがないため、フォローできません。
`lead_not_convertible`	400	リードがどのペルソナにも属していないため、ソースにできません。
`campaign_archived`	400	キャンペーンはアーカイブ済みです。再び実行するには複製してください。
`campaign_not_started`	400	キャンペーンは下書きのため、一時停止する対象がありません。
`campaign_flow_empty`	400	キャンペーンのフローにまだステップがありません。開始する前にステップを追加してください。
`column_protected`	400	この列は受信トレイやペルソナの列のようにボードに固定された列のため、削除できません。
`shared_account_has_campaigns`	400	共有ペルソナから外すXアカウントに、まだそのペルソナのキャンペーンがあります。キャンペーンを削除してから、もう一度お試しください。
`owner_cannot_leave`	400	Xアカウントのオーナーは、自分のチームを抜けられません。代わりにメンバーを外してください。
`translation_off`	400	会話の翻訳がオフになっています。オンにするか、メッセージを1件ずつ翻訳してください。
`recipient_not_messageable`	400	XがDMを拒否しました。リードがDMを閉じているか、アカウントをブロックしています。
`media_kind_unsupported`	400	この会話では、この種類のファイルを送れません。ボイスメッセージにはX Chatの会話が必要です。
`x_session_expired`	409	Xアカウントのセッションの有効期限が切れています。アプリで再接続してから、もう一度お試しください。
`assistant_busy`	409	Julien AIが、このチャットのメッセージ、またはこのXアカウントの3件のメッセージにまだ回答中です。回答を待ってから、もう一度送信してください。
`conversation_unavailable`	409	この会話には、まだメッセージを送れるXユーザーがいません。
`resource_missing`	404	キーのアカウントに、このIDのオブジェクトはありません。別のアカウントのIDでも同じ応答になります。
`route_not_found`	404	このパスにエンドポイントはありません。
`idempotency_key_reused`	409	この`Idempotency-Key`は、過去24時間以内に別のメソッド、パス、ボディで使われています。
`idempotency_key_in_use`	409	この`Idempotency-Key`を使った最初のリクエストがまだ処理中です。1秒後に再試行してください。
`rate_limit_exceeded`	429	このキーで1分間に120回を超えるリクエストがありました。`Retry-After`秒待ってください。
`export_rate_limit_exceeded`	429	このアカウントで1時間に10回を超えるエクスポートがありました。
`dm_paused`	429	Xが現在このアカウントのDMを制限しています。再開のタイミングは`Retry-After`でわかります。
`dm_rate_limited`	429	このアカウントから1分間に10件を超えるDMが送信されました。
`dm_daily_limit`	429	このアカウントからUTCの今日300件のDMが送信されたか、Xが設定した1日の上限に達しました。
`assistant_rate_limited`	429	このXアカウントからJulien AIへのメッセージが1分間に6件を超えたか、オーナー全体でアプリのチャットも含めて1時間に150件を超えました。
`assistant_daily_limit`	429	このXアカウントからJulien AIへのメッセージが、UTCの今日100件に達しました。
`passcode_rate_limited`	429	このアカウントで、X Chatのパスコードが1時間に5回を超えて試行されました。Xはすべての試行をカウントします。
`internal_error`	500	Gemlead側で予期しないエラーが発生しました。`request_id`があれば原因を特定できます。
`request_timeout`	500	リクエストに時間がかかりすぎました。再試行してください。データを変更するリクエストなら、同じ`Idempotency-Key`を使います。
`not_implemented`	501	このエンドポイントはまだ利用できません。
`upstream_unavailable`	502	XまたはGemleadのサービスが応答しませんでした。何も変更されていないので、1分後にもう一度お試しください。

エラーへの対処

400、401、403、404は、そのまま再送しても成功しません。リクエストを修正してから送り直してください。
idempotency_key_in_useの409は、1秒ほど待てば成功します。同じIdempotency-Keyで再試行してください。
429はRetry-After秒が経過すれば成功します。レート制限を参照してください。
500は少し待ってから再試行できます。データを変更するリクエストでは同じIdempotency-Keyを送り、処理が二重に実行されないようにしてください。
すべてのエラーのrequest_idをログに残してください。お問い合わせの際に、該当するリクエストをすぐに特定できます。