Dify errors come in two layers: errors when calling the app API, and errors when Dify calls a model provider. Both layers can return 401, 404, or 429, but you troubleshoot entirely different things. Watching only the status code makes it easy to keep changing configuration at the wrong layer.

This article breaks common problems into six layers, authentication, address, rate limits, workflows, context, and logs, and gives minimal reproduction commands and a fixed troubleshooting order. Error codes, limits, and interface names follow the documentation from Dify and the model provider.

Note: Dify is a trademark of its owner, and this article is not affiliated with the vendor; other product names mentioned belong to their respective owners. Examples reflect common versions as of October 2026.

1. Separate the three layers first; do not guess from the start

A single request passes through at least three layers: the client, the Dify app API, and the model provider, with a gateway possibly in between. A 401 may occur between the client and Dify or between Dify and upstream; a 404 may be a wrong path or a wrong model name; a 429 mostly comes from upstream.

Read the message, code, and request ID in the response body before deciding which layer to inspect. A practical test: call the app API directly with curl. If the same error appears, the problem is in Dify configuration or upstream; if curl works but business code fails, the problem is in the client or the network.

2. 401 and 403: do not mix the two kinds of keys

Dify has two sets of credentials: the app API key calls Dify apps, and the model provider key lets Dify call upstream models. The former goes in the Authorization: Bearer ... header; the latter is configured in model provider settings. Mixing them is the most common source of 401s.

Common causes include:

  • The header is missing Bearer, or the key has leading or trailing spaces, newlines, or quotes.
  • The key belongs to a different app. App keys are usually created per app and cannot be used across apps.
  • The key was deleted or rotated, or the workspace has no access to that app.
  • The model provider key expired, ran out of balance, was revoked, or lost characters when copied.
  • A reverse proxy, gateway, or front end stripped the Authorization header.

403 is usually about permissions: insufficient workspace role, the provider not permitting that model, or a restricted upstream account. Confirm who is calling whom first, then retest with another key.

3. 404 and model not found: check the address and the name separately

When calling the Dify app API, a 404 usually falls into three categories:

  1. Wrong Base URL: the Dify Cloud app API base is https://api.dify.ai/v1; for self-hosting, use your own domain and path. Omitting /v1 or including the full endpoint path both produce 404s.
  2. Endpoint does not match the app type: chat apps use chat-messages, workflow apps use workflows/run, and text generation apps use completion-messages. Using the wrong endpoint returns 404 or 400 even with a correct key.
  3. Reverse proxy rewrites the path: Nginx subpaths, trailing slashes, and URL rewrite rules can all send requests to a route that does not exist.

If the error comes from the model provider, the usual messages are model not found, model does not exist, or invalid model. Check whether the model ID matches the provider's current listing, including case, date suffixes, and aliases; confirm the model is enabled in Dify; and confirm the plugin version supports it. A model being retired or renamed also breaks the existing configuration.

4. 429: rate limits, concurrency, and quota

A 429 is usually not returned by Dify but by the upstream model service or gateway saying "too many requests." Triggers may be requests per minute, tokens per minute, concurrency, or account quota. Batch jobs, loop nodes, and many simultaneous users are the quickest way to spike instantaneous concurrency.

Handling order:

  • Check the response headers and error message to identify whether it is request rate, token rate, or concurrency.
  • Lower client concurrency and queue batch jobs instead of firing them all at once.
  • Retry only 429 and 5xx, with exponential backoff plus jitter and a maximum attempt count.
  • Make workflow retries idempotent: the same business request may execute nodes again, so add a deduplication key at the business layer.
  • If it happens frequently over time, consider splitting apps, keys, or projects, or shifting the calling window.

Blind retries turn a rate limit into an avalanche. Before retrying, confirm the request has not already caused side effects.

5. Workflow failures: start from node inputs and outputs

A failed workflow can usually be traced to one node. Common types:

Symptom Common cause What to check first
Empty variable reference An upstream node does not output that variable, or the name is misspelled Node output structure and variable selector
Type mismatch A string is used as an array or object Upstream node return type and conversion node
Code node error Syntax, dependency, timeout, or wrong return structure Run log and code node conventions
HTTP node failure Non-2xx, authentication error, timeout, certificate problem Status code, headers, and target service logs
LLM output parsing failure The model did not return JSON Prompt constraints and parser tolerance
Empty knowledge retrieval Index incomplete, threshold too high, or query rewrite failed Knowledge-base status and retrieval parameters
Iteration node failure Input is not an array, or the subflow references the wrong item Iteration input and item structure

Dify workflows support node-level error handling such as retries, default values, and exception branches. Giving key nodes a fallback is more controllable than failing the whole flow. Do not use defaults to hide configuration errors, though, or the problem will only surface further downstream.

6. Context and token limits

Context errors usually appear as 400 with messages like context length exceeded, maximum context, or token limit. The cause is not that "the model is bad" but that total input and output exceed the allowed range. The total includes the system prompt, conversation history, retrieved knowledge-base chunks, user input, and reserved output.

Troubleshoot by compressing each item:

  • Limit history turns, or summarize before appending.
  • Reduce the number of retrieved chunks, enable reranking, and drop irrelevant passages.
  • Adjust document chunk size to avoid overly long blocks.
  • Set a separate maximum output token count and leave room for input.
  • Estimate tokens on the application side and truncate or route to a long-context model before exceeding the limit.

The context length configured in Dify must match what the provider actually supports. Set it larger than upstream and requests are rejected; set it too small and long documents are truncated early.

7. Logs and tracing: connect a single request end to end

Troubleshooting cannot rely on the last error message alone. Keep at least four kinds of information: Dify app logs and workflow records, model provider logs, gateway request logs, and business-side user and request IDs. Dify's run records show each node's input, output, and latency, and are the first place to look for a failure.

When you need finer tracing, you can connect tracing tools; the supported observability platforms depend on your version's documentation. Whichever tool you use, record the model name, request ID, latency, input and output tokens, error code, and retry count consistently. That way 429s, timeouts, and model changes show up as trends instead of waiting for user complaints.

8. A reusable troubleshooting order

  1. Call the Dify app API directly with curl -i and record the HTTP status and response body.
  2. Confirm the Base URL, endpoint, and app type match to rule out 404.
  3. Confirm the app key and provider key are not mixed up to rule out 401.
  4. Test the model provider separately in the Dify UI to confirm upstream is available.
  5. Open the workflow run record, find the first failing node, and inspect its input and output.
  6. Check context, output limits, and knowledge-base retrieval parameters to rule out token issues.
  7. Check upstream and gateway logs for 429s, timeouts, or quota limits.
  8. After fixing, rerun the same batch of requests and watch the error rate for a while.

The minimal reproduction command follows; -i shows the status code and response headers together:

export DIFY_API_KEY="app-your-app-key"

curl -i -sS "https://api.dify.ai/v1/chat-messages" \
  -H "Authorization: Bearer $DIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {},
    "query": "Reply with OK only",
    "response_mode": "blocking",
    "user": "diag-001"
  }'

For self-hosting, replace the address with your instance; for workflow apps, use /v1/workflows/run and the matching parameters. Get a minimal request working first, then add history, knowledge bases, and tools step by step; that quickly narrows down the failing layer.

FAQ

Testing a model inside Dify succeeds, but the app API returns 401. Why?

They use different keys. Model testing uses the provider key; the app API uses the app's own key. Check that the header is Bearer plus the app key, and confirm the key belongs to the current app and workspace.

The address looks right, so why is it still 404?

The usual reasons are an endpoint that does not match the app type, or a Base URL with a missing or extra path. Dify Cloud uses https://api.dify.ai/v1; self-hosting uses the instance domain. Different app types have different endpoints, so check by type.

How many times should I retry a 429?

There is no universal number. Set a maximum retry count and total wait limit, use exponential backoff with jitter, and retry only 429 and 5xx. If it keeps happening, reduce concurrency or quota instead of retrying indefinitely.

Can the workflow continue when one node fails?

Consider node-level error handling: retries, default values, or exception branches. Use them only for nodes that can be degraded; authentication failures and parameter errors should surface directly, not be swallowed by defaults.

What if the logs do not show the original upstream error?

First check whether the Dify run record contains a node-level error, then look at the provider console and gateway logs. If upstream returns only a generic error, call the upstream endpoint directly with the same key and model name; that usually reveals more detail.

Next steps

The core of Dify troubleshooting is layering: determine whether the problem is the app API, Dify configuration, or the upstream model, then use status codes and node errors to locate it item by item. If you want a unified model entry point and centralized call logs, you can register for the ZSQH AI Gateway; models and prices are listed at model pricing.

Related reading: