mirror of
https://github.com/langgenius/dify-docs.git
synced 2026-07-23 12:55:46 -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
4.2 KiB
Plaintext
62 lines
4.2 KiB
Plaintext
---
|
||
title: エラーとレート制限の処理
|
||
sidebarTitle: エラーとレート制限
|
||
description: エラーレスポンスの共通構造、ステータスクラスごとの意味、再試行に値する失敗の見分け方
|
||
---
|
||
|
||
> このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/api-reference/guides/errors) を参照してください。
|
||
|
||
記載されているエラーは、いずれも同じ 3 フィールドの 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 でアプリのモデル設定を修正してください。
|
||
|
||
## レート制限とクォータ
|
||
|
||
2 つの 429 `code` は意味が異なります。
|
||
|
||
- `too_many_requests` は同時実行数の上限です。このアプリへの同時リクエストが今は多すぎる状態です。バックオフして再試行してください。
|
||
- `rate_limit_error` は Dify Cloud のプランクォータです（ワークフロー実行回数など）。再試行では解消されず、クォータ期間のリセットかプラン変更で解消します。
|
||
|
||
Dify Cloud では、ナレッジ系の書き込みエンドポイントもプラン制限を `403` レスポンスとして返します。`code` はアクセス制限と同じ `forbidden` のため、プラン制限かどうかは `message` でしか判別できません。403 の処理を `code` だけで分岐させないでください。
|
||
|
||
## ストリーム内のエラー
|
||
|
||
ストリームが開いた時点で、HTTP ステータスはすでに `200` です。失敗は `error` イベントとして届き、ストリームを終了させます。イベントの `code` の値はこのページに記載のものと同じで、同じルールで分類できます。詳細は [ストリーミングレスポンスの処理](/ja/api-reference/guides/streaming) を参照してください。
|
||
|
||
## 再試行の判断
|
||
|
||
- **バックオフして再試行**：`too_many_requests`、`500`、ネットワーク障害。
|
||
- **そのまま再試行しない**：バリデーションエラー（まずリクエストを修正）、認可の失敗、クォータエラー（クォータがリセットされるまで解消しない）。
|
||
- **再試行ではなく修正**：再開呼び出しの `404` は、`user` の誤りか実行が存在しないことを意味します。再試行せず、識別子を修正してください。
|