本文へスキップ

ガイド

エラー

エラーの形式と、コードごとの対処。

API のエラーはすべて、RFC 9457 形式の application/problem+json レスポンスです。

JSON
{
  "type": "https://piqline.com/docs/api/errors#insufficient_scope",
  "title": "Scope insuffisant",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "searchWeb demande le scope explore.",
  "request_id": "8c0c051b-c3e6-4fa0-8b98-0aa227cf3c2a",
  "missing_scopes": ["explore"]
}
フィールド意味
typeこのページ内で、そのエラーを説明しているセクションの URL
title短いタイトル(フランス語)
statusHTTP ステータス
codeエラーの固定識別子。判定にはこれを使います
detail読みやすい説明(フランス語)。バージョン間で変わることがあります
request_idリクエスト ID。X-Request-Id ヘッダーにも入ります

エラーによっては、missing_scopes、issues などのフィールドが追加されます。

お問い合わせの際は、request_id を添えてください。ログで該当のリクエストを特定でき、キーが有効だった場合は、設定の API と MCP にある履歴でも見つかります。フォームはお問い合わせページにあります。

コード一覧#

missing_key#

401 · API キーがありません

原因。 リクエストにキーが含まれていません。

対処。 Authorization: Bearer piq_live_…(または x-api-key)を送信してください。

invalid_key#

401 · API キーが無効です

原因。 キーの形式が正しくない(途中で切れている、または入力し直した)、不明、失効済み、期限切れ、または作成者がワークスペースを離れています。detail で、形式の問題か状態の問題かを区別できます。

対処。 コピーを確認してください。キーが失効または期限切れの場合は、設定の API と MCP で新しいキーを作成します。

insufficient_scope#

403 · スコープが不足しています

原因。 ルールまたはツールが必要とするスコープが、キーにありません。missing_scopes に一覧があります。

対処。 それらのスコープを持つキーを作成してください。既存のキーのスコープは変更できません。

forbidden#

403 · アクセスが禁止されています

原因。 キー作成者のロールでは、このツールまたはエージェントにアクセスできません。

対処。 必要なロールを持つアカウントでキーを作成してください(書き込みツール、アクションツール、オンボーディングエージェントにはオーナーまたは管理者が必要です)。

not_found#

404 · 見つかりません

原因。 ルート、ツール、エージェントのいずれかが不明です。チャットの対話カード(askUser、proposeSources、proposeBoard など)は、呼び出せるツールではありません。

対処。 有効な名前は GET/api/v1/tools と GET/api/v1/agents で確認できます。

invalid_input#

422 · 入力が無効です

原因。 本文が有効な JSON ではないか、入力がツールのスキーマに一致しません。issues が、問題のある各フィールド(path、message)を示します。

対処。 本文をツールの input_schema(GET/api/v1/tools/{nom})と照らし合わせてください。

tool_error#

422 · ツールエラー

原因。 データ固有の理由で、ツールがリクエストを拒否しました。たとえば、このワークスペースに存在しないアイテムを指定した場合です。理由は detail に書かれています。

対処。 detail に従って入力を修正してください。状況が変わらない限り、同じ呼び出しは同じ結果になります。

rate_limited#

429 · リクエストが多すぎます

原因。 キーが 1 分あたりの制限を超えました。

対処。 Retry-After ヘッダーの秒数だけ待ってから、再試行してください。呼び出しの間隔を空けてください。

quota_exceeded#

429 · 1 日のクォータに達しました

原因。 キーが 1 日のリクエスト上限に達しました。カウンターは毎日 UTC の 0 時にリセットされます。

対処。 UTC の 0 時を過ぎてから再試行してください。上限の引き上げをご希望の場合は、お問い合わせページからご連絡ください。

budget_exhausted#

402 · 月間クレジットを使い切りました

原因。 キーのワークスペースが、月間クレジットの上限に達しました。消費を伴うもの(エージェント、有料ツール、収集)は、呼び出しの前に拒否されます。実行中のエージェントのターンは、上限に達した時点で停止します。再開日は detail に書かれています。

対処。 detail に示された再開日まで待つか、ワークスペースのオーナーに上限の引き上げを依頼してください。

plan_restricted#

403 · プランに含まれていません

原因。 キーのワークスペースのプランが、このリクエストを許可していません。API が使えないか、読み取り専用で、リクエストが書き込み、購読、調査やエージェントの開始を伴っています。plan にプラン、api_access にアクセス(none、read)が示されます。

対処。 必要なアクセスを開くプランについて、Piqline にお問い合わせください。読み取りには Équipe、フルアクセスには Business です。

unavailable#

503 · サービスを利用できません

原因。 リクエストが依存するサービスが応答していません。キーの確認、エージェントのモデル、プロバイダーのいずれかです。

対処。 間隔を徐々に延ばしながら再試行してください。エラーが続く場合は、お問い合わせの際に request_id を添えてください。

not_configured#

503 · 設定されていません

原因。 サーバーで API が設定されていません。環境変数が不足しています。

対処。 お問い合わせの際に request_id を添えてください。この状態を解消できるのは Piqline だけです。

internal#

500 · 内部エラー

原因。 Piqline 側で予期しないエラーが発生しました。detail は意図的に曖昧にしています。

対処。 再試行してください。エラーが続く場合は、お問い合わせの際に request_id を添えてください。

API についてのご質問や、このページの誤りはありませんか。 お問い合わせ.