Handle Errors and Rate Limits

App and classic knowledge base endpoints return errors in the same three-field JSON envelope:

{
  "code": "invalid_param",
  "message": "user is required",
  "status": 400
}

status mirrors the HTTP status; code is the stable identifier to branch on; message is human-readable detail. Each endpoint page lists exactly which codes it can raise.

The agent knowledge base API uses the same three fields and adds a failure object to many errors. For what failure tells you and when to retry, see its Handle Errors section.

Status Classes at a Glance

Status	Meaning	Typical codes
400	The request or the app’s configuration is invalid	`invalid_param`, `bad_request`, `app_unavailable`, provider errors (below)
401	Authentication failed or access was denied	`unauthorized`
403	This action is not permitted, or a plan limit applies	`forbidden`; when the app itself can’t be used, some app endpoints return `app_not_found`, `app_abnormal_status`, `app_api_disabled`, or `workspace_archived` instead
404	The resource doesn’t exist or isn’t visible to this key or `user`	`not_found`; the conversation endpoints return `conversation_not_found`, `conversation_cursor_not_found`, `conversation_variable_not_found`, or `conversation_first_message_not_found` instead
413 / 415	A file is too large or of an unsupported type	`file_too_large`, `unsupported_file_type`
429	Too many requests right now, or a quota is exhausted	`too_many_requests`, `rate_limit_error`
500	Something failed on Dify’s side	`internal_server_error`

On Dify Cloud, a 401 response from an app API can also mean the request was blocked by IP access control. If your API key is valid, ask the app administrator to check whether the request’s source IP is allowed.

Provider Errors Are Configuration Errors

Four common 400 codes point at the app’s model setup rather than your request:

provider_not_initialize: no valid model credentials
provider_quota_exceeded: the model provider’s own quota ran out
model_currently_not_support: the model isn’t currently supported
completion_request_error: an error occurred while making a completion request

For these errors, retrying won’t help. Fix the app’s model configuration in Dify.

Rate Limits and Quotas

The two 429 codes mean different things:

too_many_requests is a concurrency ceiling—too many simultaneous requests for the app right now. Back off and retry.
rate_limit_error is a plan quota on Dify Cloud, such as workflow executions. Retrying won’t clear it; it resets with the quota period or a plan change.

On Dify Cloud, knowledge base endpoints also enforce plan limits as 403 responses, such as the request rate limit. These carry the forbidden code. Classic knowledge base endpoints use the same code for access restrictions, so read the message to tell them apart rather than switching on code alone.

Errors Inside Streams

Once an app stream opens, the HTTP status is already 200: failures arrive as an error event and end the stream. The event’s code values are the same ones documented here—classify them with the same rules. See Consume Streaming Responses for details.

What to Retry

Retry with backoff: too_many_requests, 500, and network failures.
Don’t retry as-is: validation errors (fix the request first), authorization failures, or quota errors (they won’t clear until the quota does).
Fix, don’t retry: a 404 from a resume call means the wrong user or a run that doesn’t exist. Correct the identifier instead.

Guides

App APIs

Knowledge APIs

Handle Errors and Rate Limits

Status Classes at a Glance

Provider Errors Are Configuration Errors

Rate Limits and Quotas

Errors Inside Streams

What to Retry

​Status Classes at a Glance

​Provider Errors Are Configuration Errors

​Rate Limits and Quotas

​Errors Inside Streams

​What to Retry

Status Classes at a Glance

Provider Errors Are Configuration Errors

Rate Limits and Quotas

Errors Inside Streams

What to Retry