响应与错误编码

客户端需要分别判断 HTTP 状态和业务状态。HTTP 200 不等于业务成功；认证、参数等业务异常也可能以 HTTP 200 返回 JSON。

普通/分页包装的逐字段定义见请求与响应约定，本页重点说明失败分类与安全处理。

普通业务与分页

普通接口成功示例：

{
  "code": 8200,
  "message": "SUCCESS",
  "data": {}
}

分页在顶层增加 pageNo、pageSize、total、totalPage，data 为数组。不同接口成功 data 可能是对象、数组、字符串或布尔值，应遵循该接口定义，不以 data 是否非空判断成功。

对话接口成功直接返回对话对象或 SSE，Dify 检索直接返回 records；这些成功响应不使用 code=8200 的包装。失败时应同时检查实际 Content-Type 和错误体。

HTTP 状态	说明
200	请求得到响应，仍须检查业务 code 或该接口成功结构
400	请求格式等错误，可能由网关或框架返回
401	登录状态缺失或过期等，常见业务码 8302
403	用户权限不足，常见业务码 8403
413	上传体积超过允许范围；网关可能不返回 AIS JSON
429	标准 Chat 触发接口限流；如有 Retry-After，按其秒数延后重试
500、502、503、504	服务或网关异常，保留时间及响应信息排查

code	含义或常见场景	处理建议
8200	普通业务成功	按接口解析 data
400	OpenAPI 参数非法	检查字段、范围和必填约束
401	AccessDenied；密钥、渠道凭据无效或平台密钥模块权限不足	检查凭据类型、有效期及权限；不能仅凭此码区分原因
413	请求体过大	调整上传体积
429	请求限流或账户余额不足等	结合响应说明区分原因；余额不足不应按限流无限重试
8302	未登录或登录失效	检查请求头并更新凭据
8400	部分业务参数异常	按具体接口修正请求
8401	不允许的操作等历史业务异常	结合具体接口响应处理，不统一解释为密钥过期
8402	参数校验、业务断言失败	修正参数；访客编码重复也可能走此错误分支
8403	用户或接口访问权限不足	补齐对应角色或访问权限
8404	未找到资源，包括用户或文件不存在	检查编码及所属租户、知识库
8405	请求数据不存在	检查前置资源
8406	请求超时	核实操作结果后决定是否重试
8407	请求非法或不允许删除	检查操作条件
8408	请求凭据过期	刷新凭据
8409	请求数据错误	修正业务数据
8410	重复操作	查询当前状态
500、8500	内部或未归类业务异常	保留请求上下文排查，不对写操作盲目重试
8888	License 不存在、过期或能力未授权	联系部署方确认授权

状态来源包括不同代际的业务枚举，同一类失败可能使用不同码。尤其不能照搬旧对接资料中“所有参数错误都是 8400”“所有 API Key 错误都是 8401”的映射。

典型认证失败：

{
  "code": 401,
  "message": "请求中的 ApiKey 错误",
  "data": null
}

message 的语言受 Accept-Language 和服务端配置影响，失败 data 也可能为空字符串。程序按 code、HTTP 状态及接口语义处理，message 用于展示和排查。

只读查询可以在短暂网络失败后有限重试。注册和创建超时后先按稳定 code 查询；充值可能重复记账，用户 /fire 会切换状态，权限更新为全量替换，均不应自动重复执行。

SSE 建流前可能返回 JSON 错误，建流后应识别流内错误、结束原因与中断。记录请求时间、接口路径和业务编码，避免记录完整密钥、契约 Token 和含凭据的兑换 URL。