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

# MuleRouter provider error reference

> MuleRouter error codes, detailed messages, and task failures returned through GENGEN.

Verified against the [official error catalog](https://mulerouter.ai/docs/get-started/error-codes)
on October 5, 2026. It contains 29 codes, including five category fallback codes.
The official catalog does not define codes 4006 or 4007.

This policy covers FlashVSR, Wan 2.7, Wan Animate, z-image, Qwen Image Edit, and
Face Swap across public API and creator workspace operations.
Known HTTP request errors use the mapped GENGEN `error_code`; the original
provider code stays in `error_params.upstreamCode`. The HTTP status and existing
[error envelope](/help/errors) are preserved. Unknown codes keep
`provider.request_failed`, with the original code and a usable detailed explanation.

Descriptions prefer upstream `detail`, then `message`, then `title`.
Explicit authentication credentials and internal accounting values are redacted.
Accounting includes upstream balances, reservation amounts, costs, prices,
credits, markup, and multipliers. The reason for a failure, parameter names,
input limits, request IDs, and business URLs remain available. Business download
and session query parameters retain their original encoding; URL usernames and
passwords are removed. Empty, non-text, HTML, or non-JSON explanations fall back
to a generic message. Other providers keep their existing policies.

<Note>
  Upstream account, balance, permission, and configuration errors are operational
  issues for GENGEN administrators. API users should contact GENGEN support;
  adding funds to their GENGEN wallet does not resolve upstream account errors.
</Note>

## Error codes

The HTTP column is the upstream reference status, not a rule for rewriting responses.
For example, a successfully retrieved failed task still has HTTP 200.

| Upstream code | GENGEN error\_code | Reference HTTP | Meaning |
| - | - | - | - |
| `1000` | `provider.mulerouter_user_error` | 401 | Account error without a more specific code. |
| `1001` | `provider.mulerouter_authentication_failed` | 401 | The upstream credential is missing, invalid, expired, or revoked. |
| `1002` | `provider.mulerouter_permission_denied` | 403 | The upstream account or key cannot access the requested resource. |
| `1003` | `provider.mulerouter_insufficient_balance` | 402 | The upstream account cannot fund or reserve this request. |
| `1004` | `provider.mulerouter_rate_limit_exceeded` | 429 | The upstream key, account, or model request rate limit was exceeded. |
| `1005` | `provider.mulerouter_quota_exceeded` | 429 | An upstream concurrency, storage, or other non-rate quota was exceeded. |
| `2000` | `provider.mulerouter_input_validation_failed` | 400 | Input validation failed without a more specific code. |
| `2001` | `provider.mulerouter_parameter_validation_failed` | 400 | The request does not satisfy the endpoint parameter schema. |
| `2002` | `provider.mulerouter_required_parameter_missing` | 400 | A required request parameter is missing. |
| `2003` | `provider.mulerouter_invalid_parameter_value` | 400 | A well-formed parameter has a value the endpoint cannot accept. |
| `2004` | `provider.mulerouter_parameter_combination_conflict` | 400 | The supplied parameters conflict or are unsupported together. |
| `2005` | `provider.mulerouter_resource_not_found` | 404 | The referenced task, model configuration, or other resource does not exist. |
| `2100` | `provider.mulerouter_file_validation_failed` | 400 | File validation failed without a more specific code. |
| `2101` | `provider.mulerouter_file_size_exceeded` | 400 | An input file exceeds the endpoint size limit. |
| `2102` | `provider.mulerouter_unsupported_file_format` | 400 | An input file format is unsupported. |
| `2103` | `provider.mulerouter_file_content_error` | 400 | An input file is corrupt or cannot be decoded. |
| `3000` | `provider.mulerouter_upstream_service_error` | 500 | The model service failed without a more specific code. |
| `3001` | `provider.mulerouter_upstream_service_unavailable` | 500 | The model service is temporarily unreachable. |
| `3002` | `provider.mulerouter_upstream_service_request_failed` | 500 | The model service rejected the request; retrying unchanged input will not resolve it. |
| `3003` | `provider.mulerouter_upstream_service_response_error` | 500 | The model service returned an unexpected or unparseable response. |
| `3004` | `provider.mulerouter_upstream_service_timeout` | 500 | The model service did not respond within the allowed time. |
| `3005` | `provider.mulerouter_upstream_service_execution_failed` | 500 | The model service accepted the task but could not finish it; read the detailed reason. |
| `4000` | `provider.mulerouter_system_error` | 500 | MuleRouter failed without a more specific system code. |
| `4001` | `provider.mulerouter_service_temporarily_unavailable` | 500 | MuleRouter is temporarily unable to serve the request. |
| `4002` | `provider.mulerouter_internal_operation_failed` | 500 | A required MuleRouter internal operation failed. |
| `4003` | `provider.mulerouter_internal_dependency_unavailable` | 500 | A MuleRouter internal dependency is unavailable. |
| `4004` | `provider.mulerouter_internal_dependency_failed` | 500 | A MuleRouter internal dependency failed during the request. |
| `4005` | `provider.mulerouter_configuration_error` | 500 | A required upstream server configuration is missing or invalid. |
| `4008` | `provider.mulerouter_task_execution_timeout` | 500 | An asynchronous task exceeded the server execution limit and was cancelled. |

## Request errors

An upstream balance rejection keeps HTTP 402 and is distinct from a GENGEN wallet
rejection using `seedance.insufficient_balance`.

```json theme={"dark"}
{
  "error_code": "provider.mulerouter_insufficient_balance",
  "error_params": {
    "provider": "flash-vsr",
    "service": "flash-vsr",
    "status": 402,
    "upstreamCode": 1003
  },
  "error": "Upstream provider: Insufficient balance to complete this request. Required: [redacted billing], Available: [redacted billing] (request_id: example-request)"
}
```

## Asynchronous task failures

The official [asynchronous task guide](https://mulerouter.ai/docs/get-started/async-tasks)
places failures in `error.error_code`; model OpenAPI definitions also use
`task_info.error.code`. GENGEN reads both, including their `title` and `detail`.
Common terminal codes are 3001-3005, 4002, and 4008.

A task lookup returns HTTP 200 with `status: failed`, a detailed `failureReason`,
and an optional structured `error` containing the mapped `code`, original
`upstreamCode`, and sanitized `message`. Successful and pending tasks do not
receive a manufactured failure object. The standard fields remain first.

```json theme={"dark"}
{
  "id": "flashvsr:example-task",
  "model": "flashvsr",
  "status": "failed",
  "outputs": { "videos": [], "images": [] },
  "failureReason": "The input video could not be decoded.",
  "error": {
    "code": "provider.mulerouter_upstream_service_execution_failed",
    "upstreamCode": 3005,
    "message": "The input video could not be decoded."
  }
}
```

## Handling and support

Branch on the GENGEN code and task status, not message wording. Correct parameter
or file errors before submitting again. Code 3002 needs a change or investigation;
an unchanged retry is not a fix. Code 3005 needs its detailed explanation to
distinguish rejected content, invalid media, and other execution failures.
This catalog does not introduce automatic retries or change wallet settlement.

When contacting support, include the request time, HTTP status, GENGEN code,
original upstream code, provider request ID, and public task ID when available.
Never include an API key. Internal server diagnostics retain accounting context
with authentication credentials masked.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.