ガイド
エラー
エラーの形式と、コードごとの対処。
API のエラーはすべて、RFC 9457 形式の application/problem+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 | 短いタイトル(フランス語) |
status | HTTP ステータス |
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 を添えてください。