> ## Documentation Index > Fetch the complete documentation index at: https://mulerouter.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Error Codes ## HTTP Status Codes HTTP status codes are used to indicate the status of a request. ### Success Response (200 - 299) The following status codes indicate a successful response. | Response Status Code | Description | | :------------------- | :------------------------------------------------------------------------------------------------------------------------------------ | | **200 OK** | The synchronous task executed successfully and returned the result. | | **201 Created** | The task was created successfully and a new resource was created (e.g., a session). | | **202 Accepted** | The request has been accepted but not yet processed; it does not indicate the final outcome (e.g., creation of an asynchronous task). | ### Client Error Response (400 - 499) The following status codes indicate a client error. | Response Status Code | Description | | :------------------------------------ | :---------------------------------------------------------------------------------------------------------- | | **400 Bad Request** | Invalid request parameters (e.g., malformed body, incorrect fields). | | **401 Unauthorized** | Unauthorized (e.g., token expired or invalid). | | **402 Payment Required** | Payment required (e.g., insufficient balance or subscription required). | | **403 Forbidden** | Forbidden (e.g., insufficient permissions to access the resource). | | **404 Not Found** | The requested resource was not found (e.g., incorrect path or unknown task id). | | **405 Method Not Allowed** | Method not allowed (e.g., attempting to create an async task via a synchronous endpoint). | | **409 Conflict** | Conflict (e.g., attempting to create an asynchronous task that already exists). | | **423 Locked** | The requested resource is locked (e.g., attempting to write to a resource that is currently being written). | | **429 Too Many Requests** | Too many requests (e.g., rate limit, quota, or daily spend limit exceeded). | | **451 Unavailable For Legal Reasons** | Unavailable for legal reasons. | ### Server Error Response (500 - 599) The following status codes indicate a server error. You can try again later. If the error continues, please contact us for assistance. | Response Status Code | Description | | :---------------------------- | :----------------------------------------------------------------- | | **500 Internal Server Error** | Server error (e.g., an unknown error occurred on the server). | | **502 Bad Gateway** | Bad gateway (e.g., an upstream service returned an error). | | **503 Service Unavailable** | Service unavailable (e.g., our service is experiencing an outage). | ## MuleRouter Errors When a synchronous request fails, MuleRouter returns an [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) formatted error body. HTTP Status Code. Refer to [HTTP Status Codes](#http-status-codes) for more details. Short title of the error. MuleRouter Error Code. Refer to [MuleRouter Error Codes](#mulerouter-error-codes) for more details. A URI reference that identifies the specific occurrence of the problem. A URI reference that identifies the problem type. Description of the error. For example: ```json theme={null} { "status": 400, "title": "Parameter validation failed", "error_code": 2001, "instance": "/vendors/alibaba/v1/videos/generation", "type": "https://mulerouter.ai/docs/get-started/error-codes#2001", "detail": "'model' expected one of 'wan2.2-t2v-plus', 'wan2.5-t2v-preview', got 'invalid-model'" } ``` ### Errors in asynchronous task results For an [asynchronous task](/docs/get-started/async-tasks), the HTTP `POST` that creates the task only fails synchronously when the request itself is malformed (e.g. validation errors `2xxx`, authentication errors `1xxx`). Once the task is accepted (HTTP `202`), any subsequent failure surfaces when you `GET` the task — the `task_info.status` becomes `failed` and the response carries an `error` object with the same shape as above: ```json theme={null} { "task_info": { "id": "123e4567-e89b-12d3-a456-426614174000", "status": "failed", "created_at": "2025-09-16T10:00:00Z", "updated_at": "2025-09-16T10:02:13Z" }, "error": { "title": "External service execution failed", "error_code": 3005, "detail": "Kling task failed: video generation failed due to prompt violation" } } ``` Asynchronous tasks most commonly surface the following codes in their `error` payload: * `3001` – `3005`: the upstream model provider could not complete the task. * `4002`, `4008`: a MuleRouter-side error occurred while running the task. In all these cases the HTTP status of the `GET` response itself is `200` — the task lookup succeeded, but the task it describes failed. The `error_code` is the authoritative signal for what went wrong. ## MuleRouter Error Codes MuleRouter business error codes are grouped by category. Within each category, the `x000` code is the abstract base class for that category (used as a fallback when no more specific code applies), and `x001+` are concrete cases. | Range | Category | Typical HTTP status | | :----- | :---------------------------------------------- | :---------------------------------------------------- | | `1xxx` | User account, authentication, billing, quota | 401 / 402 / 403 / 429 | | `2xxx` | Input validation (parameters, files, resources) | 400 / 404 | | `3xxx` | Upstream model provider errors | 500 (also surfaced inside async task `error` payload) | | `4xxx` | MuleRouter system errors | 500 | ### 1000 – 1999 · User errors Errors related to the caller's account, credentials, balance, and limits. #### 1000 User Error Base class for user-related errors. Used as a fallback when no more specific user error applies. * **HTTP**: 401 #### 1001 Authentication Failed API Key is missing, invalid, expired, or revoked. * **HTTP**: 401 #### 1002 Permission Denied The caller is authenticated but is not allowed to access the resource — for example, a temporary key being used in production, or a key without the required scope. * **HTTP**: 403 #### 1003 Insufficient Balance The account does not have enough credits to start or hold for the request. * **HTTP**: 402 #### 1004 Rate Limit Exceeded The QPS / QPM / QPD limit for the key, user, or model has been exceeded. * **HTTP**: 429 #### 1005 Quota Exceeded A non-rate quota has been exceeded — e.g. maximum concurrent asynchronous tasks, or a storage quota. * **HTTP**: 429 ### 2000 – 2999 · Input validation errors Errors related to the shape and content of the request. #### 2000 Input Validation Failed Base class for input validation errors. * **HTTP**: 400 #### 2001 Parameter Validation Failed Request body or query parameters failed schema or type validation — malformed JSON, type mismatch, enum mismatch, bad `resolution` / `size` strings, etc. * **HTTP**: 400 #### 2002 Required Parameter Missing A required field is missing. Typical for fields that are mandatory only for certain models (e.g. `resolution` is required for some video models for pricing). * **HTTP**: 400 #### 2003 Invalid Parameter Value The parameter is well-formed but its value is rejected: unsupported model name, unknown task type, unsupported resolution, out-of-range `duration`, etc. * **HTTP**: 400 #### 2004 Parameter Combination Conflict Mutually exclusive parameters were provided together, or a parameter is not supported by the chosen model (e.g. `audio` provided with a model that does not support it; multiple images provided to a single-image model). * **HTTP**: 400 #### 2005 Resource Not Found The referenced resource does not exist — most importantly **the task id is unknown** when calling `GET /vendors/.../tasks/{task_id}` (or its `*-task` variant). Also used for unknown model configurations. * **HTTP**: 404 #### 2100 File Validation Failed Base class for file-related validation errors. * **HTTP**: 400 #### 2101 File Size Exceeded A submitted file exceeds the per-endpoint size limit (e.g. image > 50 MB, mask > 4 MB). * **HTTP**: 400 #### 2102 Unsupported File Format The submitted file's MIME type is not in the allow-list (e.g. mask must be PNG, image must be `image/*`). * **HTTP**: 400 #### 2103 File Content Error The file is the right format on paper but its content cannot be decoded or is corrupted (e.g. Base64 decode failure, unreadable image). * **HTTP**: 400 ### 3000 – 3999 · Upstream service errors Errors raised when the upstream model provider fails. These are the codes you will most often see inside an **asynchronous task's `error` payload** after the task transitions to `failed`. #### 3000 Upstream Service Error Base class for upstream service errors. Used as a fallback when no more specific upstream error applies. * **HTTP**: 500 #### 3001 Upstream Service Unavailable The upstream provider was temporarily unreachable. Try again later. * **HTTP**: 500 #### 3002 Upstream Service Request Failed The upstream provider rejected the request. The request will not succeed on retry without changes. * **HTTP**: 500 #### 3003 Upstream Service Response Error The upstream provider returned an unexpected or unparseable response. * **HTTP**: 500 #### 3004 Upstream Service Timeout The upstream provider did not respond within the allowed time. Try again later. * **HTTP**: 500 #### 3005 Upstream Service Execution Failed The upstream provider accepted the request but reported that the task itself failed (for example, the generation was rejected, content was filtered, or the provider returned an execution error). **This is the most common terminal error for async tasks.** * **HTTP**: 500 ### 4000 – 4999 · System errors Errors that happened inside MuleRouter rather than at the upstream. Async tasks may report `4002` or `4008` in their `error` payload when the failure happens on our side. #### 4000 System Error Base class for MuleRouter system errors. Used as a fallback when no more specific system error applies. * **HTTP**: 500 #### 4001 Service Temporarily Unavailable MuleRouter is temporarily unable to serve the request. Try again later. * **HTTP**: 500 #### 4002 Internal Operation Failed MuleRouter could not complete an internal operation required by the request. Try again later. * **HTTP**: 500 #### 4003 Internal Dependency Unavailable A MuleRouter internal dependency is temporarily unavailable. Try again later. * **HTTP**: 500 #### 4004 Internal Dependency Failed A MuleRouter internal dependency returned an error while processing the request. Try again later. * **HTTP**: 500 #### 4005 Configuration Error A required server-side configuration is missing or invalid. If this persists, please contact support. * **HTTP**: 500 #### 4008 Task Execution Timeout A server-side safety-net timeout for an asynchronous task: the task ran longer than the maximum allowed execution time and was cancelled. * **HTTP**: 500