指南
错误
错误的格式,以及每个错误码的处理方法。
每个 API 错误都是 application/problem+json 响应,格式遵循 RFC 9457:
{
"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 · 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。