# エラー

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

Source: https://piqline.com/ja/docs/api/errors

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` | 短いタイトル（フランス語） |
| `status` | HTTP ステータス |
| `code` | エラーの固定識別子。判定にはこれを使います |
| `detail` | 読みやすい説明（フランス語）。バージョン間で変わることがあります |
| `request_id` | リクエスト ID。`X-Request-Id` ヘッダーにも入ります |

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

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

## コード一覧

### `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 時を過ぎてから再試行してください。上限の引き上げをご希望の場合は、[お問い合わせページ](/contact)からご連絡ください。

### `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` を添えてください。
