> ## Documentation Index
> Fetch the complete documentation index at: https://enterprise-docs.dify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Handle Errors and Rate Limits

> The error envelope, what each status class means, and which failures are worth retrying

Every documented error uses the same three-field JSON envelope:

```json theme={null}
{
  "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

| Status | Meaning | Typical codes |
| :- | :- | :- |
| 400 | The request or the app's configuration is invalid | `invalid_param`, `bad_request`, `app_unavailable`, provider errors (below) |
| 401 | Missing or invalid API key | `unauthorized` |
| 403 | The key can't act here: access restrictions | `forbidden` |
| 404 | The resource doesn't exist or isn't visible to this key or `user` | `not_found` |
| 413 / 415 | A file is too large or of an unsupported type | `file_too_large`, `unsupported_file_type` |
| 429 | Too many simultaneous requests for this app | `too_many_requests` |
| 500 | Something failed on Dify's side | `internal_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](/en/3.13.x/develop/api/guides/streaming) 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.