本文档由 AI 自动翻译。如有任何不准确之处，请参考 英文原版。
文档中列出的每个错误都采用同一种三字段 JSON 结构：
{
"code": "invalid_param",
"message": "user is required",
"status": 400
}
status 与 HTTP 状态码一致；code 是稳定的标识符，适合作为分支判断的依据；message 是供人阅读的详细信息。每个接口页面都会列出它可能返回的所有 code。
状态码类别速览
| 状态码 | 含义 | 典型 code |
|---|
| 400 | 请求或应用配置无效 | invalid_param、bad_request、app_unavailable、供应商错误（见下文） |
| 401 | API 密钥缺失或无效 | unauthorized |
| 403 | 该密钥无权执行此操作：访问受限或达到套餐限制 | forbidden |
| 404 | 资源不存在，或对该密钥或 user 不可见 | not_found |
| 413 / 415 | 文件过大或类型不受支持 | file_too_large、unsupported_file_type |
| 429 | 当前请求过多，或配额已用尽 | too_many_requests、rate_limit_error |
| 500 | Dify 侧出现故障 | internal_server_error |
供应商错误是配置错误
有 4 个常见的 400 code 指向应用的模型配置，而不是你的请求本身：
provider_not_initialize：没有有效的模型凭据provider_quota_exceeded：模型供应商自身的配额已用尽model_currently_not_support：当前不支持该模型completion_request_error：发起文本生成请求时出错
这些错误重试无济于事，需在 Dify 中修复应用的模型配置。
速率限制与配额
两个 429 code 的含义并不相同：
too_many_requests 是并发上限：应用此刻的同时请求过多。退避后重试即可。rate_limit_error 是 Dify Cloud 的套餐配额（如工作流执行次数）。重试无法消除，只会随配额周期重置或套餐变更而解除。
在 Dify Cloud 上，知识库写入接口还会以 403 响应实施套餐限制。这些响应携带的 code 与访问受限相同，都是 forbidden，只能靠 message 判断是不是套餐限制，因此不要只根据 code 来分支处理 403。
流中的错误
流一旦打开，HTTP 状态码就已经是 200：失败会以 error 事件的形式到达并结束整个流。事件中的 code 取值与本页所列相同，按同样的规则分类处理即可。详见 处理流式响应。
哪些错误值得重试
- 退避后重试：
too_many_requests、500 和网络故障。
- 不要原样重试：参数校验错误（先修正请求）、鉴权失败，以及配额错误（配额未重置前不会消失）。
- 修正而非重试：恢复调用返回的
404 意味着 user 不对或运行不存在。改正标识符即可。
Last modified on July 9, 2026
