MuleRouter provider error reference

Verified against the official error catalog 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 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.

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.

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.

{
  "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 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.

{
  "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.

​Error codes

​Request errors

​Asynchronous task failures

​Handling and support

Error codes

Request errors

Asynchronous task failures

Handling and support