Skip to main content
Every documented error uses 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.

​
Status Classes at a Glance

StatusMeaningTypical codes
400The request or the app’s configuration is invalidinvalid_param, bad_request, app_unavailable, provider errors (below)
401Missing or invalid API keyunauthorized
403The key can’t act here: access restrictionsforbidden
404The resource doesn’t exist or isn’t visible to this key or usernot_found
413 / 415A file is too large or of an unsupported typefile_too_large, unsupported_file_type
429Too many simultaneous requests for this apptoo_many_requests
500Something failed on Dify’s sideinternal_server_error

​
Provider Errors Are Configuration Errors

Two common 400 codes point at the app’s model setup rather than your request:
  • provider_not_initialize: no valid model credentials
  • 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

The 429 code too_many_requests is a concurrency ceiling—too many simultaneous requests for the app right now. Back off and retry.

​
Errors Inside Streams

Once a 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) or authorization failures.
  • 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.