结果、错误与退出码

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

输出去向#

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

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

读取运行结果#

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

判断运行如何结束#

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

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

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

{  "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 输出的错误：

{  "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，即服务器的完整响应。

退出码#

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

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

具体错误的解决方法，可到 故障排查 中查找。

重试失败的命令#

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

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

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

对于退出码 2 和 4，在解决标志写错、登录过期 等问题之前，每次重试都会得到同样的退出码。

限流#

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

每次登录每分钟最多可发送 60 次请求。在自部署的服务器上，可设置 OPENAPI_RATE_LIMIT_PER_TOKEN 调整上限，设为 0 则关闭限流。

故障排查#