错误

API 使用标准 HTTP 状态码并返回一致的错误响应体。所有错误包含机器可读的错误码和人可读的消息。

错误响应格式

所有错误返回包含 error 字段的 JSON 对象，包括错误码、消息和 HTTP 状态。

HTTP 状态码

状态码	含义
`200`	成功
`400`	错误请求——请求参数无效或请求体格式错误
`401`	未授权——API 密钥无效或缺失
`402`	积分不足——账户余额不足以完成本次请求
`403`	禁止访问——权限不足
`404`	未找到——资源不存在
`409`	冲突——资源已存在（如邮箱已注册）
`429`	请求过多——超出速率限制
`500`	内部服务器错误

错误码

错误码	HTTP 状态码	描述
`BAD_REQUEST`	`400`	请求体格式错误或缺少必填字段
`UNAUTHORIZED`	`401`	API 密钥无效、缺失或已被撤销
`INSUFFICIENT_CREDITS`	`402`	账户积分不足，请充值后重试
`FORBIDDEN`	`403`	没有权限访问该资源
`NOT_FOUND`	`404`	请求的资源未找到
`CONFLICT`	`409`	资源冲突（如重复注册）
`RATE_LIMIT_EXCEEDED`	`429`	已超出速率限制，请根据 Retry-After 头等待后重试
`MODEL_NOT_FOUND`	`400`	指定的模型不存在或未激活，请通过 GET /v1/models 查看可用模型列表
`UPSTREAM_ERROR`	`502`	上游服务（搜索、引用检测等）返回错误或超时
`PROVIDER_ERROR`	`502`	LLM 提供商返回错误（如内容过滤、上下文过长等）
`BILLING_ERROR`	`500`	计费系统在扣费/结算时发生错误
`SEARCH_FAILED`	`500`	论文搜索执行失败
`ANALYSIS_FAILED`	`500`	论文分析执行失败
`INTERNAL_ERROR`	`500`	服务端发生意外错误

示例

import requests

response = requests.post(
    "https://api.qinyanai.com/v1/paper-search/google",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"query": "machine learning"}
)

if response.status_code != 200:
    error = response.json()["error"]
    print(f"Error {error['code']}: {error['message']}")
else:
    data = response.json()
    print(f"Found {len(data['data'])} papers")

Response

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient credits: available=0.50, required=1.00",
    "detail": null
  }
}