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

# 结果、错误与退出码

> 看懂 difyctl 命令输出的内容，判断一次运行是怎样结束的，并处理错误、退出码、重试与限流

> 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/cli/reference/results-errors-and-exit-codes.md)。

## 输出去向

命令的结果一律以 JSON 输出到 stdout，错误和通知则输出到 stderr：

* 错误：在终端中显示为文本；如果把 stderr 重定向到文件或交给其他程序（例如 `2> errors.log`），则以 JSON 输出。要让终端中的错误也以 JSON 显示，加上 `--json`。
* 通知（如 `stream ended early: …`）：始终是纯文本。

## 读取运行结果

`run console_app` 命令的结果包含应用的回答，以及后续操作要用到的 ID：

| 字段 | 内容 |
| :- | :- |
| `text.answer` | 聊天助手、旧版 Agent 应用、Chatflow 应用或文本生成应用的回复。运行 Workflow 应用时为空。 |
| `outputs` | Workflow 应用的回答，键名对应输出节点的变量。Chatflow 应用会在这里再给出一次回复，并附上它返回的文件（如有）。 |
| `run_id` | Workflow 或 Chatflow 应用的运行 ID，可传给 `describe run` 和 `get run node`。 |
| `conversation_id` | 聊天助手、旧版 Agent 应用或 Chatflow 应用的会话 ID，用 `--conversation-id` 传回即可继续会话。 |

### 判断运行如何结束

在脚本中，应读取结果的 `status`。运行无论是正常结束、中途暂停还是被截断，退出码都是 0，要靠 `status` 来区分：

* `ended`：运行已结束。
* `suspended`：运行在人工介入表单处暂停。结果的 `hints` 为每个操作按钮各给出一条命令，要 [填写表单](/zh/cli/run-apps.md#填写人工介入表单)，运行与你所选操作对应的那条即可。
* `incomplete`：运行还没结束，结果就被截断了，例如你按下了 Ctrl+C。结果中只有截断前已收到的内容。Workflow 或 Chatflow 应用的运行仍会在服务器上继续，要查看它最终如何结束，把结果中的 `run_id` 传给 `difyctl describe run`。
* `failed`（退出码 1）：运行失败或被停止，原因见 `error.message`。

运行失败时，结果和其他运行一样打印到 stdout，stderr 上没有任何输出。例如，运行 Workflow 应用时漏传了必填输入：

```json theme={null}
{
  "status": "failed",
  "text": {
    "answer": ""
  },
  "hints": [],
  "run_id": "f16c3509-ef54-4618-ae93-770724ab278d",
  "total_tokens": 0,
  "error": {
    "message": "topic is required in input form"
  }
}
```

## 解读错误信息

命令如果在产生结果之前就失败，stdout 上不会有任何输出，错误会打印到 stderr。下面是传入不存在的应用 ID 时，以 JSON 输出的错误：

```json theme={null}
{
  "error": {
    "code": "server_error",
    "message": "app not found",
    "http_status": 404,
    "method": "GET",
    "url": "https://dify.example.com/openapi/v1/apps/00000000-0000-4000-8000-000000000000",
    "server": {
      "code": "not_found",
      "message": "app not found",
      "status": 404
    }
  }
}
```

每个错误都带有 `code` 和 `message`，脚本要根据 `code` 走不同分支。根据失败原因，错误还可能带有以下字段：

* `hint`：用一句话说明下一步可以怎么做，例如 `run difyctl help get console_app`。
* `http_status`、`method`、`url` 和 `server`（服务器自身的错误）：错误由服务器返回时才会带有。遇到 `server_error` 时，根据 `http_status` 或 `server.code` 走不同分支，例如上例中的 `404` 和 `not_found`。
* `details`：某个值没有通过 `difyctl` 自身的校验（`input_invalid`）时才会带有，列出每个校验失败的字段及其标志和原因，例如 `"field": "--limit", "msg": "must be integer"`。

在终端中，如果服务器给出了自己的错误码，错误的第一行会显示这个错误码，所以上例中找不到应用的错误显示为 `not_found: app not found`。脚本分支时要用 JSON 中的错误码，这里是 `server_error`。

如果 `message` 说不清失败原因，加上 `--verbose`，错误中就会带上 `raw_response`，即服务器的完整响应。

## 退出码

每条命令退出时都会返回以下某个退出码：

| 退出码 | 含义 | 错误码 |
| :- | :- | :- |
| 0 | 成功，包括暂停（`suspended`）或被截断（`incomplete`）的运行 | |
| 1 | [运行失败](#判断运行如何结束)，或其他各行未涵盖的错误，例如服务器错误或网络错误 | `server_error`、`network_connection`、`keyring_unavailable`、`skill_missing`、`unknown` |
| 2 | `difyctl` 在发送前就拒绝了命令：标志未知、缺少必填标志，或值的类型不对 | `usage_invalid_flag`、`usage_missing_arg`、`input_invalid`、`config_invalid_key`、`config_invalid_value` |
| 4 | 未登录、登录已过期，或没有访问权限 | `not_logged_in`、`auth_expired`、`access_denied` |
| 6 | 服务器上没有这条命令，或 `difyctl` 无法获取服务器的命令列表 | `unknown_op`、`catalog_unavailable` |
| 7 | 触发了 [限流](#限流) | `rate_limited` |

退出码为 1 时，先看 stdout，运行失败的结果就输出在那里。其他错误都在 stderr 中。

具体错误的解决方法，可到 [故障排查](#故障排查) 中查找。

## 重试失败的命令

读取类命令（如 `get` 和 `describe`）可放心重试。`help` 会在每条命令的描述旁显示它的标签：`read`、`write` 或 `destructive`。

重试 `write` 或 `destructive` 命令前，先确认第一次是否已经生效，例如用对应的 `get` 或 `describe` 命令查看。运行类命令属于 `write`，重试会另起一次新的运行。

遇到退出码 7 时，任何命令都可放心重试，运行类命令也不例外：被 [限流](#限流) 拒绝的命令在服务器上什么都没做。

对于退出码 2 和 4，在解决标志写错、[登录过期](/zh/cli/manage-sign-in.md#续期登录) 等问题之前，每次重试都会得到同样的退出码。

### 限流

命令以退出码 7 退出时，等待 1 分钟后再重试。

每次登录默认每分钟最多可发送 60 次请求。要调整上限，在服务器上设置 [`OPENAPI_RATE_LIMIT_PER_TOKEN`](/zh/self-host/deploy/configuration/environments#dify-cli-与编程-api)，设为 `0` 则关闭限流。

## 故障排查

| 错误信息 | 错误码 | 处理方法 |
| :- | :- | :- |
| `invalid bearer` | `auth_expired` | 登录已过期或已失效。[重新登录](/zh/cli/manage-sign-in.md#续期登录)。 |
| `not logged in: …` | `not_logged_in` | 先登录。如果已经登录，将 `DIFY_CONFIG_DIR` 指向登录时所用的配置目录。 |
| 因情况而异，例如 `insufficient workspace role` | `access_denied` | 你的工作空间角色或某项工作空间设置（例如谁可以安装集成）不允许此操作。 |
| `no command or server operation named <words>` | `unknown_op` | 用 `difyctl help` 核对命令。如果拼写无误，说明服务器的 Dify 版本没有这条命令。 |
| `failed to fetch the catalog: …` | `catalog_unavailable` | 确认服务器正在运行，且登录时用的地址正确。 |
| `<method> <url> timed out after <ms>ms` | `network_connection` | 调高 [`http.timeout`](/zh/cli/reference/configuration#设置)。 |
| `Internal Server Error`（HTTP 503），每条命令都出现 | `server_error` | 在服务器上将 `ENABLE_OAUTH_BEARER` 设为 `true`。 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.