Docs错误码

错误码 (Errors)

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

错误响应结构

所有错误响应均遵循以下结构:

JSON

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

HTTP 状态码

成功

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

客户端错误

代码	状态	说明
`400`	Bad Request	请求格式错误(如日期格式错误、IPC 代码错误或未知的 `applicant_match`)。
`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: psk_live_... 请求头。

已停用的 API 密钥

403 Forbidden

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

密钥存在但已被停用。如需重新发行密钥,请联系我们。

超过月度检索额度

429 Too Many Requests

{
"detail": "Daily limit exceeded (30/30). Upgrade your plan at https://findip.ai/pricing"
}

已达到检索额度。额度按结算日每月自动重置。详情查询、附图、编号查询不计入额度。请在使用量仪表盘查看当前状态。

请求校验错误

422 Unprocessable Entity

{
"detail": "query field required"
}

缺少必填字段,或字段类型/取值不正确。请查看 Search API 的请求结构。

无效参数

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"。
设置合理的请求超时(检索 30 秒,其他端点建议 10 秒)。

认证 (Auth)Next: 开发者指南