Troubleshoot

Dify API — Troubleshooting

For auth/base URL fundamentals see the setup skill.

HTTP status & error format

Errors return JSON like:

{ "status": 400, "code": "invalid_param", "message": "..." }

Common pitfalls

Conversation/messages come back empty or 404

The user field is the scope key. If you create a conversation with user: "a" and then list with user: "b", you get nothing. Use the same user string for the same person on every call. Also note: Service API users and WebApp users are separate namespaces — a conversation created in the WebApp is not visible via the Service API and vice-versa.

Blocking request times out (~100s)

On Dify Cloud, blocking mode is behind a ~100-second proxy timeout. Long generations or multi-step workflows will drop the connection. Use response_mode: "streaming" for chat UIs, long outputs, and workflows.

inputs rejected / variable errors

The inputs object must contain exactly the variables defined in the app's user_input_form. Call GET /parameters first and send {} only if the app has no required variables.

File upload not accepted

• Upload with multipart/form-data (use --form), not JSON.
• Include the user form field — it scopes the file.
• The file type/extension/size must be allowed by the app's file_upload config (GET /parameters). Reference it later with { "transfer_method": "local_file", "upload_file_id": "<id>" }.

Audio endpoints fail

/audio-to-text and /text-to-audio require the app to have an STT / TTS model configured. Without it you'll get a model/config error — enable the model in the app settings.

Stop endpoint does nothing

Stop only works in streaming mode, needs the task_id from a streamed event (not the message_id / workflow_run_id), and the user must match the run's user.

Wrong key for Knowledge Base calls

Knowledge Base / Datasets endpoints use a Knowledge API key (dataset-…), not an app key (app-…). Using the app key returns 401/403.

Rate limits

• Dify Cloud applies plan-based rate limits. Inspect response headers when present: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
• On 429, wait and retry with exponential backoff; honor Retry-After if returned.
• Self-hosted has no built-in API rate limiting (configure at your proxy/gateway).

Debugging checklist

1. Base URL ends with /v1?
2. Correct key type (app-… for Service API, dataset-… for Knowledge API)?
3. user present and consistent?
4. inputs match GET /parameters?
5. Long output → streaming instead of blocking?
6. For stop/detail → using task_id vs workflow_run_id correctly?
7. Reproduce with curl -v to see status code and the code/message body.