mirror of
https://github.com/langgenius/dify-docs.git
synced 2026-07-22 04:15:24 -04:00
Riskey
7ccb166cb6
* docs: add New Agent user guide and node tab
* docs: add ENABLE_AGENT_V2 to environment variable reference
* translate: add zh and ja New Agent documentation
* docs: add New Agent navigation groups
* feat: add limits and quotas rule to style guide
* docs: add skill and file upload limits to New Agent guide
* fix: redirect new-agent doc paths from UI links to self-host pages
* docs: add task examples and refine New Agent pages
* docs: update New Agent data security notice per legal
* docs: extend security notice coverage and build note explanation
Surface the legal data security Warning on the Build page and New Agent node tab (en/zh/ja), and explain the build note as the agent's memory across build chats with an example.
* docs: refine New Agent guidance and cross-link from classic Agent
Model note gains the older-model sandbox symptom; node opener differentiates from the classic node; Build page restructured (review bullets, Info callout, section links) with zh/ja synced; classic Agent app page (self-host) gains a New Agent Tip.
* docs: document memory, permissions, and sandbox facts for New Agent
Verified additions: per-conversation memory bounded by the model's context window; Editor-tier permissions for creating and managing agents; unrestricted sandbox network access; version restore excludes the sandbox environment; build note deletion and regeneration behavior.
* docs: rename Roster to Agent page across New Agent docs
The UI removed the Roster concept; the nav entry is now Agent. Updated pages, node tab titles, image alt text, and the ENABLE_AGENT_V2 reference entry in en/zh/ja. Agent Console button labels are unchanged in the UI and stay verbatim.
* docs: add files vs knowledge guidance and restructure page openers
Decision aid for uploading as Files vs connecting a knowledge base (read-in-full vs search), knowledge opener gains relevance and workspace-asset framing, overview and build intros restructured.
* docs: update docker compose container list and add tool prerequisites (#843)
* docs: update docker compose container list and add tool prerequisites
- Add api_websocket and init_permissions to the started-container list per the current compose defaults
- Remove outdated sample outputs for docker compose up and docker compose ps
- Add a callout noting the clone command requires git, curl, and jq, with recovery guidance on command not found errors
- Mirror all changes to zh and ja
* docs: note expected exited status for init_permissions container
* fix: align tools page tab titles across languages and fix anchors
Shorten the Swagger and Workflow tab titles ("Swagger API as Tool" ->
"Swagger API", "Workflow as Tool" -> "Workflow") in en, zh, and ja so all
three languages generate the same tab anchors. Update the inbound links in
output.mdx that pointed at the old Workflow-tab anchor (#workflow-as-tool,
#工作流作为工具, #ワークフローをツールとして利用) to #workflow.
* feat: consolidate and restructure the API reference (Phase 1) (#846)
* docs: correct HITL API integration flow and sync translations
- Fix the claim that the resume endpoint differs per app type (same
endpoint; only the entry endpoint differs)
- Tie workflow_run_id guidance to the human_input_required event
(chatflow message chunks don't carry it)
- Require the same user when resuming the event stream (mismatch
returns 404); add include_state_snapshot and continue_on_pause
guidance
- Note at the capture step that a null form_token means Email delivery
- Soften the upload-time validation claim to file size limits
- Split long paragraphs; align zh endpoint name with the reference page
* fix: correct API references against verified backend behavior
Audit of the Service API specs against dify hotfix/1.15.0-fix.1, with
every change code-verified and the serious items adversarially
confirmed. Applies to en/zh/ja.
- Add curl samples for GET endpoints with required query params
(Mintlify omits query params from generated snippets)
- Document 401 once in every spec's auth scheme description
- Correct wrong facts: workflow run detail returns inputs as a JSON
string; DELETE /conversations requires a JSON body; audio-to-text
accepts audio/{mp3,m4a,wav,amr,mpga} by MIME type; workflow log
created_by_account filters by email; triggered_from values are
app-run/webhook/schedule/plugin; stop endpoints' user semantics
differ per app type
- Remove unreachable docs: phantom text_replace SSE event, annotation
403, file preview endpoint in the workflow spec, invented
score_threshold bounds
- Make upload user optional (DEFAULT-USER fallback), fix upload
response example, add missing invalid_param error
- Declare text_to_speech.autoPlay in parameters responses (prose
values, no response-field enums)
* fix: complete API reference audit for knowledge and completion specs
* feat: add API spec consolidation pipeline
Phase-1 of the API docs consolidation: tooling that merges the five per-app-type Service API specs into one openapi_service.json per language, with every divergence resolved explicitly in resolutions.json and rendering-preserving namespacing for mode-scoped schema families. Includes the audit lint and parity checks (lint taught the new language-prefixed href scheme), hand-merged mode-aware SSE documentation for POST /chat-messages in en/zh/ja, and the New Agent (Beta) virtual nav group with code-verified mode notes.
* feat: consolidate API reference into one spec per language
Emit {en,zh,ja}/api-reference/openapi_service.json (82 ops, 130 components) from the audit-fixed per-app-type specs; wire docs.json to them with explicit per-app-type endpoint lists, x-mint.href URLs (/{lang}/api-reference/{tag}/{summary} with shared English slugs for in-place language switching), 265 redirects covering the legacy en and CJK URLs, per-app-type overview pages including New Agent (Beta), and rewritten legacy API links in 21 MDX bodies. The old five specs per language stay as pipeline input; they are no longer rendered.
* fix: remove dead conversation_completed error from chat specs
ConversationCompletedError is never raised anywhere at the verified 1.15.0 ref (7a4252b3de): controllers catch it, but no service code raises it, so the documented 400 conversation_completed can never fire. Remove the bullet and example from the chat and chatflow /chat-messages docs in en/zh/ja. Found and adversarially confirmed during the New Agent (PR #836) verification; filed on the upstream bug list.
* feat: add membership matrix and restructure nav config
* feat: rename resource tags and update all references
* feat: stamp per-operation availability lines
* feat: wire three-group API navigation
* feat: add app-type page coverage lint
* docs: rewrite chatflow overview as app-type API guide
* docs: polish chatflow overview zh and ja wording
* docs: rewrite workflow overview as app-type API guide
* docs: align workflow overview details across languages
* docs: expand new agent overview into app-type API guide
* docs: use task-oriented heading on new agent overview
* docs: rewrite chatbot and agent overview as app-type API guide
* docs: rewrite text generator overview as app-type API guide
* docs: match end user link text to merged spec summary
* docs: rewrite knowledge overview as app-type API guide
* docs: move knowledge api guide into api reference
* docs: localize ui labels on knowledge overview
* docs: refresh pipeline readme for restructure modes
* docs: name app-type pages in the guides sidebar
* feat: rename zh completion messages tag to match resource framing
* docs: prototype endpoints-first layout on chatflow overview
* docs: correct detail accuracy on chatflow overview
* docs: move human input flow guide into api reference
Move the shared HITL API integration walkthrough from its six per-product
copies into {en,zh,ja}/api-reference/guides/human-input-flow as the first
task guide in the API docs. Guides gains an App Types subgroup (expanded
by default) with the flow guide after it; six redirects cover the old
paths; the Human Input node docs and the chatflow overview link to the
new home.
* fix: update spec links to the moved human input guide
* fix: let spec lint accept mdx guide pages under api-reference
* docs: align chatflow zh and ja overviews to endpoints-first layout
* docs: polish chatflow zh and ja mode terms and hitl wording
* docs: align workflow overviews to endpoints-first layout
* docs: document form expiry path in human input flow guide
* docs: align new agent overviews to endpoints-first layout
* docs: align chatbot and agent overviews to endpoints-first layout
* docs: align text generator overviews to endpoints-first layout
* docs: align knowledge overviews to endpoints-first layout
* docs: correct built-in metadata examples and agent heading
* docs: flatten app-type pages directly under guides
* docs: make guide pages self-contained and trim reference detail
* docs: add get started guide and retire developing-with-apis
* docs: update new agent api behavior for latest main
New Agent behavior re-verified against dify origin/main (f3ba2846):
agent_thought events now stream through the Service API carrying the
model's reasoning steps and tool calls; a new agent_not_published 400
fires on Send Chat Message and Get App Parameters; the files claim is
softened to contents-not-processed (raw references now reach the prompt;
runtime confirmation pending). Streaming-only, message_end metadata, and
the endpoint surface are unchanged.
* docs: audit fixes for get started and human input flow guides
* docs: fix em dash spacing and ja sentence length in get started
* docs: move message_end note to the send endpoint line
* docs: update writing guides and API skill for app-type naming
- Glossary and zh/ja translation guides: Workflow and Chatflow app types stay English (Workflow 应用 / Chatflow アプリ); lowercase workflow localizes to 工作流 / ワークフロー.
- formatting-guide: API reference links use the language prefix with English slugs.
- dify-docs-api-reference skill: Spec Structure documents source specs merged into openapi_service.json by the pipeline.
* feat: add operation sidebar titles and simplify API redirects
- merge_specs stamps x-mint.metadata.sidebarTitle per operation so translated summaries show in the sidebar.
- Redirects reduced to a catch-all to the English API home plus three knowledge-base exceptions.
- memberships, strings, and SSE overrides carry app-type labels (Workflow/Chatflow English, New Agent, API Overviews group).
* docs: correct app-type naming and translations across API specs
- English mode enum labels Chatflow and Workflow apps.
- zh/ja app references use Workflow/Chatflow; New Agent is 新 Agent / 新しい Agent.
- ja knowledge tag データセット becomes ナレッジベース; zh 模型提供商 becomes 模型供应商.
- Regenerate merged openapi_service.json with per-operation sidebar titles.
* docs: add streaming, errors, and end-user identity API guides
- Consume Streaming Responses: response modes, SSE parsing, event dispatch, and reconnect.
- Handle Errors and Rate Limits: the error envelope, status classes, and retry guidance.
- End User Identity: what the user field scopes and why it stays consistent.
- English source with zh and ja translations.
* docs: reconcile API guides and apply app-type naming
- Reader-test fixes and content audit on get-started and the app-type overview pages.
- zh/ja reconciled to the English source.
- Workflow/Chatflow and New Agent naming applied in prose.
* feat: wire API nav and redirects for consolidated guides
- Rename the guides group to API Overviews and register the new guide pages.
- Redirects: catch-all to the English API home plus three product-embedded knowledge-base links to the Knowledge guide.
* fix: normalize zh model-provider term to 模型供应商
Aligns the POSITION_PROVIDER_* descriptions with the canonical glossary term.
* docs: use Info callouts for guide forward-link notes
Wrap the authentication, base URL, and `user` field forward-reference in each app-type guide (agent, chat, chatflow, completion, workflow; en/zh/ja) in an `<Info>` callout.
* refactor: remove one-time analyze mode and verification compose
- Drop the `analyze` mode (design-time spec-overlap analysis) and its helpers; the merge is stable and nothing invokes it.
- Delete `compose.swagger.yml`, the throwaway local code-vs-spec verification stack (flagged in review for inline credentials).
- README: drop the analyze entry and correct the redirect description.
* fix: correct Chatflow naming and reasoning wording in SSE overrides
- Use "Chatflow" (English) for the app type in the `/chat-messages` SSE tables instead of 对话流/チャットフロー, and fix the legacy zh chatflow "对话流工作流" description. Standalone table cells were missed by the earlier app-type rename.
- Describe `reasoning_chunk` as "reasoning content" in en/ja (matching the `reasoning` field and the zh wording) instead of "chain-of-thought".
* docs: refine API guide wording and simplify the human-input example
* docs: standardize Workflow and Chatflow app-type capitalization
Capitalize Chatflow and Workflow when they name an app type; keep "workflow" lowercase for the general engine, graph, or run sense.
* fix: use 供应商 for model provider in the zh Knowledge spec
* fix: rename the Knowledge API nav group to "Knowledge APIs"
* fix: un-deprecate Update Document by Text in the Knowledge spec
* translate: un-deprecate Update Document by Text in zh/ja specs
Mirror the en fix (6802d5eb) into the zh and ja Knowledge specs, source and merged: drop the deprecated flag and the leading Deprecated notice from the update-by-text operation. It is the canonical text-update route; only Update Document by File stays deprecated.
* fix: repoint tools node links to the Classic Agent tab anchor
The Tool Configuration heading is now nested inside the Classic Agent tab, so #tool-configuration no longer resolves. Point the three Tools-page links (en/zh/ja) at the tab-title anchor instead.
* fix: correct broken bold and dropped text in ja/zh Agent node
Pre-existing classic-content translation flaws surfaced in review: the ja ReAct bold cycle was mangled and missing Thought; the zh Memory sentence had dropped text.
* docs: document New Agent deployment and 1.16.0-rc1 availability
Retire the sandbox-container placeholder. The availability Notes, the node-page Note, and a new environments "New Agent (Beta)" section now point to the Dify 1.16.0-rc1 release, note it's on by default on Docker Compose, and call out DIFY_AGENT_SERVER_SECRET_KEY as the one value to set. Also aligns the ja data-security Warning with the zh single-tenant wording. en/zh/ja.
* fix: relink publish API Integration card to the API reference (#847)
* docs: standardize workflow casing in key-concepts and environments
* translate: apply Workflow/Chatflow app-type naming to zh/ja docs
* translate: sync API-guide copy-edits to zh/ja
* fix: correct New Agent API guide against the current runtime
Verified against feat/agent-v2: the reply streams as agent_message events (not message), list-message agent_thoughts carries the turn's reasoning steps (not empty), uploaded files are surfaced to the agent as downloadable references (not ignored), and /meta tool_icons is empty for New Agent apps. Adds the 1.16.0-rc1 availability pointer to the beta note. en/zh/ja.
* docs: use Tip for New Agent availability callouts and tidy API guides
Switch the New Agent availability callouts (overview, build, node) from Note/Info to Tip; the node callout gains the on-by-default sentence. Tighten the API guide beta Info and restructure the get-started API-key section into bullets. zh/ja synced to the en edits.
* fix: point home page API Reference card at the new API guide
* fix: rename Agent nav references to Agents to match the UI
The main-nav item and its page are now labeled Agents (plural), rendered as a literal in routes.ts and roster/page.tsx. Update the bolded nav/page references across the New Agent guide, node page, and environment reference. en/zh/ja.
* fix: add one-hop developing-with-apis redirects for all URL forms
* fix: document both New Agent reply events in the streaming contract
The New Agent guide said replies stream as agent_message; the Send Chat Message SSE reference and the streaming guide said message. Verified against dify feat/agent-v2 (agent_app/app_runner.py and its unit tests): both fire — the reply streams incrementally as agent_message deltas, then the turn closes with a single message event carrying the complete answer, then message_end, with agent_thought alongside throughout. Document the full sequence on all three surfaces and tell clients to treat the closing message as the final answer rather than appending it. en/zh/ja; merged specs regenerated via the API pipeline (build + wire, coverage clean).
62 lines
3.0 KiB
Plaintext
62 lines
3.0 KiB
Plaintext
---
|
||
title: 处理错误与速率限制
|
||
sidebarTitle: 错误与速率限制
|
||
description: 错误响应的统一结构、各状态码类别的含义，以及哪些失败值得重试
|
||
---
|
||
|
||
> 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/api-reference/guides/errors)。
|
||
|
||
文档中列出的每个错误都采用同一种三字段 JSON 结构：
|
||
|
||
```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` 取值与本页所列相同，按同样的规则分类处理即可。详见 [处理流式响应](/zh/api-reference/guides/streaming)。
|
||
|
||
## 哪些错误值得重试
|
||
|
||
- **退避后重试**：`too_many_requests`、`500` 和网络故障。
|
||
- **不要原样重试**：参数校验错误（先修正请求）、鉴权失败，以及配额错误（配额未重置前不会消失）。
|
||
- **修正而非重试**：恢复调用返回的 `404` 意味着 `user` 不对或运行不存在。改正标识符即可。
|