Skip to main content

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.

​
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 CodeDescription
200 OKThe synchronous task executed successfully and returned the result.
201 CreatedThe task was created successfully and a new resource was created (e.g., a session).
202 AcceptedThe 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 CodeDescription
400 Bad RequestInvalid request parameters (e.g., malformed body, incorrect fields).
401 UnauthorizedUnauthorized (e.g., token expired or invalid).
402 Payment RequiredPayment required (e.g., insufficient balance or subscription required).
403 ForbiddenForbidden (e.g., insufficient permissions to access the resource).
404 Not FoundThe requested resource was not found (e.g., incorrect path or unknown task id).
405 Method Not AllowedMethod not allowed (e.g., attempting to create an async task via a synchronous endpoint).
409 ConflictConflict (e.g., attempting to create an asynchronous task that already exists).
423 LockedThe requested resource is locked (e.g., attempting to write to a resource that is currently being written).
429 Too Many RequestsToo many requests (e.g., rate limit, quota, or daily spend limit exceeded).
451 Unavailable For Legal ReasonsUnavailable 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 CodeDescription
500 Internal Server ErrorServer error (e.g., an unknown error occurred on the server).
502 Bad GatewayBad gateway (e.g., an upstream service returned an error).
503 Service UnavailableService unavailable (e.g., our service is experiencing an outage).

​
MuleRouter Errors

When a synchronous request fails, MuleRouter returns an RFC 7807 formatted error body.
​
status
integer
required
HTTP Status Code. Refer to HTTP Status Codes for more details.
​
title
string
required
Short title of the error.
​
error_code
integer
required
MuleRouter Error Code. Refer to MuleRouter Error Codes for more details.
​
instance
string
A URI reference that identifies the specific occurrence of the problem.
​
type
string
A URI reference that identifies the problem type.
​
detail
string
Description of the error.
For example: 
{
  "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, 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: 
{
  "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.
RangeCategoryTypical HTTP status
1xxxUser account, authentication, billing, quota401 / 402 / 403 / 429
2xxxInput validation (parameters, files, resources)400 / 404
3xxxUpstream model provider errors500 (also surfaced inside async task error payload)
4xxxMuleRouter system errors500

​
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