# 错误

> 错误的格式，以及每个错误码的处理方法。

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

每个 API 错误都是 `application/problem+json` 响应，格式遵循 RFC 9457：

```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** · Scope 不足

**原因。** 密钥缺少路由或工具所需的 scope。`missing_scopes` 列出这些 scope。

**处理方法。** 创建带有这些 scope 的密钥。已有密钥的 scope 保持不变：无法修改。

### `forbidden`

**403** · 禁止访问

**原因。** 密钥创建者的角色无权使用该工具或智能体。

**处理方法。** 用具有所需角色的账号创建密钥（写入工具、操作工具以及 onboarding 智能体需要所有者或管理员）。

### `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** · 请求过多

**原因。** 密钥已超出每分钟限制。

**处理方法。** 等待 `Retry-After` 请求头中给出的秒数后重试，并拉开调用间隔。

### `quota_exceeded`

**429** · 已达每日配额

**原因。** 密钥已达到每日请求上限。计数器每天 UTC 午夜重置。

**处理方法。** UTC 午夜之后再试。如需提高上限，请通过[联系页面](/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`。
