> ## Documentation Index
> Fetch the complete documentation index at: https://enterprise-docs.dify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 处理错误与速率限制

> 错误响应的统一结构、各状态码类别的含义，以及哪些失败值得重试

文档中列出的每个错误都采用同一种三字段 JSON 结构：

```json theme={null}
{
  "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` |
| 500 | Dify 侧出现故障 | `internal_server_error` |

## 供应商错误是配置错误

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

* `provider_not_initialize`：没有有效的模型凭据
* `completion_request_error`：发起文本生成请求时出错

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

## 速率限制

429 的 `code` 是 `too_many_requests`，表示并发上限：应用此刻的同时请求过多。退避后重试即可。

## 流中的错误

流一旦打开，HTTP 状态码就已经是 `200`：失败会以 `error` 事件的形式到达并结束整个流。事件中的 `code` 取值与本页所列相同，按同样的规则分类处理即可。详见 [处理流式响应](/zh/3.13.x/develop/api/guides/streaming)。

## 哪些错误值得重试

* **退避后重试**：`too_many_requests`、`500` 和网络故障。
* **不要原样重试**：参数校验错误（先修正请求）和鉴权失败。
* **修正而非重试**：恢复调用返回的 `404` 意味着 `user` 不对或运行不存在。改正标识符即可。