SDK 错误处理

失败响应统一是：

{
  "error": "错误原因"
}

当前版本没有独立的业务错误码字段。错误处理以 HTTP 状态码为准。

状态码

状态码	含义	处理方式
200	请求成功	正常读取返回体。
202	任务已创建	保存 task_id，再查询任务状态或日志。
400	请求参数错误	检查 JSON、字段名、问卷链接、二维码文件。
404	任务不存在	检查任务 ID，或重新读取任务列表。
502	上游问卷平台解析失败	检查问卷是否开放、链接是否可访问，稍后重试。
500	服务内部错误	查看服务日志。

POST JSON 接口会拒绝未知字段。字段名写错会得到 400。

接口错误速查

接口	可能状态码	常见原因
GET /api/health	200	服务正常。
GET /api/version	200	服务正常。
POST /api/surveys/parse	400	JSON 无效、字段名错误、url 为空。
POST /api/surveys/parse	502	问卷平台访问失败、链接不支持、问卷关闭、需要登录。
POST /api/configs	400	JSON 无效、字段名错误。
POST /api/configs	502	传入 url 后解析问卷失败。
POST /api/tasks	400	JSON 无效、字段名错误、任务保存失败。
GET /api/tasks	200	成功返回任务列表。
GET /api/tasks/{id}	404	任务 ID 不存在。
POST /api/tasks/{id}/stop	404	任务 ID 不存在。
GET /api/tasks/{id}/logs	400	after 或 limit 参数不合法。
GET /api/tasks/{id}/logs	404	任务 ID 不存在。
POST /api/qrcode/decode	400	表单无效、缺少 image 文件、二维码无法解析出问卷链接。
POST /api/qrcode/decode	500	临时文件、文件读取或服务内部处理失败。

错误返回示例

400

优先检查这些问题：

• JSON 是否合法。
• Content-Type 是否正确。
• 字段名是否写错。
• 是否传了服务不认识的字段。
• url 是否为空。
• 日志 after 是否为非负整数。
• 日志 limit 是否在 1 到 1000 之间。
• 二维码上传字段名是否为 image。

示例：

{
  "error": "JSON 请求体无效: json: unknown field \"taskTarget\""
}

URL 为空：

{
  "error": "url 不能为空"
}

日志游标错误：

{
  "error": "日志游标必须是非负整数"
}

日志条数错误：

{
  "error": "日志条数必须是 1 到 1000 之间的整数"
}

二维码文件缺失：

{
  "error": "缺少 image 文件"
}

404

只会出现在任务相关接口。

先调用 GET /api/tasks 确认任务是否存在。

示例：

{
  "error": "任务不存在"
}

502

通常是问卷平台访问失败、问卷关闭、问卷需要登录、链接不支持、网络异常。

调用方可以提示用户检查问卷链接，再做有限次数重试。

示例：

{
  "error": "无法获取题目: 问卷已停止，无法作答"
}

500

通常是服务内部文件、临时文件、数据库或二维码处理异常。

调用方应提示用户查看 SurveyCore 服务日志。

接入方建议

SDK 封装时建议只暴露三类结果：

类型	判断方式	给用户的提示
成功	status 为 200 或 202	正常返回数据。
用户可修复错误	400、404	提示检查参数、字段名、任务 ID、二维码文件。
外部或服务错误	502、500	提示稍后重试，必要时查看 SurveyCore 服务日志。

创建任务接口的 202 不是任务成功。它只表示任务已经创建。

后续要用 GET /api/tasks/{id} 看 status，或者用 GET /api/tasks/{id}/logs 读取详细日志。