处理错误与速率限制

本文档由 AI 自动翻译。如有任何不准确之处，请参考英文原版。

应用和经典知识库的接口都以同一种三字段 JSON 结构返回错误：

{
  "code": "invalid_param",
  "message": "user is required",
  "status": 400
}

status 与 HTTP 状态码一致；code 是稳定的标识符，适合作为分支判断的依据；message 是供人阅读的详细信息。每个接口页面都会列出它可能返回的所有 code。

Agent 知识库 API 同样使用这三个字段，并会在很多错误中附带 failure 对象。failure 提供了哪些信息、何时该重试，详见其处理错误部分。

状态码类别速览

状态码	含义	典型 `code`
400	请求或应用配置无效	`invalid_param`、`bad_request`、`app_unavailable`、供应商错误（见下文）
401	身份验证失败或访问被拒绝	`unauthorized`
403	不允许执行此操作，或受到套餐限制	`forbidden`；应用本身无法使用时，部分应用接口会改为返回 `app_not_found`、`app_abnormal_status`、`app_api_disabled` 或 `workspace_archived`
404	资源不存在，或对该密钥或 `user` 不可见	`not_found`；会话接口则改为返回 `conversation_not_found`、`conversation_cursor_not_found`、`conversation_variable_not_found` 或 `conversation_first_message_not_found`
413 / 415	文件过大或类型不受支持	`file_too_large`、`unsupported_file_type`
429	当前请求过多，或配额已用尽	`too_many_requests`、`rate_limit_error`
500	Dify 侧出现故障	`internal_server_error`

在 Dify Cloud 上，应用 API 返回的 401 响应也可能表示请求被 IP 访问控制拦截。如果 API 密钥有效，请应用管理员检查请求的来源 IP 是否在允许范围内。

有 4 个常见的 400 code 指向应用的模型配置，而不是你的请求本身：

这些错误重试无济于事，需在 Dify 中修复应用的模型配置。

两个 429 code 的含义并不相同：

在 Dify Cloud 上，知识库接口的套餐限制也以 403 返回，例如请求频率限制。这些响应的 code 为 forbidden。经典知识库接口在访问受限时也使用这个 code，因此要靠 message 区分两者，不要只根据 code 分支处理。

应用的流一旦打开，HTTP 状态码就已经是 200：失败会以 error 事件的形式到达并结束整个流。事件中的 code 取值与本页所列相同，按同样的规则分类处理即可。详见处理流式响应。