Docs错误码

错误码 (Errors)

Findip API 使用标准 HTTP 状态码,并返回包含错误详情的 JSON 响应。

错误响应结构

大多数错误响应遵循以下结构:

JSON

{
"detail": "可读的错误信息"
}

唯一的例外是 422 请求校验错误 —— 此时 detail 不是字符串,而是按字段列出的错误对象数组。请先判断类型,不要直接当作字符串处理。

HTTP 状态码

成功

代码	状态	说明
`200`	OK	请求成功。

客户端错误

代码	状态	说明
`400`	Bad Request	请求格式错误(如日期格式错误、IPC 代码不足 4 个字符,或同时省略 `query`、`image_url` 与 `sequence`)。
`401`	Unauthorized	缺少或无效的 API 密钥。请检查 `X-API-Key` 请求头。
`403`	Forbidden	API 密钥已被停用。
`422`	Unprocessable Entity	请求校验失败(缺少必填字段,或类型/取值错误)。
`429`	Too Many Requests	检索点数不足，或触发每分钟60次请求的速率限制。请升级套餐；付费套餐也可等待下个结算周期重置。

服务器错误

代码	状态	说明
`500`	Internal Server Error	服务器发生未预期错误(含嵌入失败)。请稍后重试。
`503`	Service Unavailable	服务器暂时不可用(维护、负载过高或认证服务故障)。

常见错误场景

API 密钥缺失或错误

401 Unauthorized

{
"detail": "Missing X-API-Key header"
}

401 Unauthorized

{
"detail": "Invalid API key"
}

请确认请求中包含 X-API-Key: pmk_live_... 请求头。

已停用的 API 密钥

403 Forbidden

{
"detail": "API key is deactivated"
}

密钥存在但已被停用。签约客户可在控制台的 API 密钥页面创建新密钥。

检索点数不足

未使用的检索点数不会结转至下个周期。检索点数无现金价值，也不得转让至其他账户。服务器接受的文本检索消耗1点，图像（附图）检索、序列检索与趋势分析消耗2点，详情、附图与编号查询消耗0点。若LLM为生成一个回答而多次检索，服务器接受的每次检索都会分别消耗点数。各操作的单价请参见认证文档中的表格。

每分钟API请求限制与点数分开统计请求数，其中也包括消耗0点的调用。detail文本及可选元数据可能随后端版本变化，客户端应按HTTP 429状态处理，不要解析提示字符串。请在使用量仪表盘查看点数余额。

请求校验错误

422 Unprocessable Entity

{
"detail": [
  {
    "type": "string_type",
    "loc": ["body", "query"],
    "msg": "Input should be a valid string",
    "input": 123
  }
]
}

字段的类型或取值与结构不符。loc 给出出错的字段路径,msg 给出原因。请查看 Search API 的请求结构。

发送未定义的字段并不会报错 —— 服务器会静默忽略并返回 200,因此参数名拼写错误不会表现为错误,而是表现为未生效的过滤结果。

无效参数

400 Bad Request

{
"detail": "invalid date: '2024/01/01' (expected YYYY-MM-DD)"
}

专利详情中的逐项 not_found

POST /api/v1/patents/details 即使某些 ID 无法解析也会返回 200 OK。无法解析的 ID 不会作为顶层错误出现,而是在 patents 数组中以 {"patent_id": "...", "error": "not_found"} 形式呈现。请逐项检查。

200 OK (partial)

{
"patents": [
  { "patent_id": "KR1020230012345A", "metadata": { ... }, "content": "..." },
  { "patent_id": "US99999999B2", "error": "not_found" }
]
}

错误处理最佳实践

解析响应 body 之前,务必先检查 HTTP 状态码。
遇到 429 与 500 时,使用指数退避 (Exponential Backoff) 重试。
出于排错目的,记录完整错误响应日志。detail 字段包含定位原因的关键信息。
对于 POST /api/v1/patents/details,即使返回 200 也请逐项检查 error: "not_found"。
设置合理的请求超时。检索通常在 2–6 秒内完成,建议留出余量设为 30 秒;文献详情、附图、覆盖范围等其他端点建议 10 秒。

认证 (Auth)