跳到正文

指南

错误

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

每个 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简短标题,用法语书写
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 · 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 午夜之后再试。如需提高上限,请通过联系页面联系我们。

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 有疑问,或发现本页有误? 联系我们.