> ## 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.11.x/develop/api/guides/streaming)。

## 哪些错误值得重试

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