Skip to Content
Slloy Docs
Generation, Settlement & Safeguards

Error Classification & Channel Fault Attribution

How Slloy maps raw upstream errors from Ark, DashScope, and Kling into 11 localized user-facing failCodes and 3 operator fault categories.

Slloy separates user-facing failure guidance (server/src/failReason.ts) from operator-facing channel fault attribution (server/src/channelFault.ts).

  • failReason.ts (FailCode): Answers "What should we tell the user in their language so they know whether to change their photo, edit their prompt, or simply wait while their refunded credits are available?"
  • channelFault.ts (FaultKind): Answers "Is our provider account out of balance / missing model activation (config), experiencing a temporary rate-limit/5xx (transient), or rejecting a bad user input (permanent)?"

1. The 11 User-Facing failCodes (server/src/failReason.ts)

Every failed row in generations stores one of 11 canonical FailCode values in generations.fail_code. Rules in RULES are evaluated in strict priority order from most specific to most general:

PriorityFailCodeUpstream Match Patterns / Internal ReasonsUser Guidance & Self-Recovery
1INPUT_PRIVACYInputImageSensitiveContentDetected.PrivacyInformationUploaded photo contains a real human face or private info blocked by provider policy. Ask user to switch photo or model (or triggers portraitBridge on Seedance 2.x).
2INPUT_SENSITIVEInputImageSensitiveContentDetected, InputImageDataInspection, InputDataInspectionFailed, Input data may contain inappropriate content, green net check.*(input|image), 绿网.*(输入|图片)Uploaded reference image failed content safety inspection. User should replace the reference image.
3OUTPUT_SENSITIVEOutput data may contain inappropriate content, green net check / 绿网, Output(Image|Video)SensitiveContentDetected, OutputDataInspectionFailed, DataInspectionFailedGenerated output triggered content safety / Green Net filter. User should soften prompt wording or try another image.
4PROMPT_SENSITIVEInputTextSensitiveContentDetected, InputTextDataInspection, prompt.*(sensitive|blocked), 内容审核.*输入Text prompt triggered safety filter. User should revise prompt text.
5IP_RISKIPInfringement, Copyright(Suspect|Infringement), TrademarkSuspect, PortraitRightDashScope copyright, trademark, or portrait-right block. Remove brand names or celebrity references.
6PARAM_UNSUPPORTEDduration customization is not supported, InvalidParameter, Parameter(s) not supported, unsupported.*(duration|size|resolution)Model does not support the requested parameter combination. Deterministic parameter bug if triggered via standard UI.
7BUSYThrottling, RequestLimitExceeded, RequestsRateLimitExceeded, TooManyRequests, rate limit, ARK_HTTP_429, DS_HTTP_429, ConcurrentRequestsExceededUpstream provider rate-limited or queue congested. Credits refunded; retry shortly.
8TIMEOUTAbortError, TimeoutError, ETIMEDOUT, ERR_TIMEOUT, DS_TASK_TIMEOUT, aborted due to timeout, or internal reason exceeded_max_ageUpstream request or async task exceeded timeout (120s image / 6h video / 10m image sweeper). Credits refunded.
9UPSTREAM_ERRORECONNRESET, ECONNREFUSED, ENOTFOUND, fetch failed, ARK_HTTP_5xx, DS_HTTP_5xx, InternalError, ModelNotOpen, Arrearage, ARK_VIDEO_POLL_404, ARK_NO_URL, or internal reasons no_task_id, channel_unreachable, succeeded_without_urlProvider service error, network failure, or account configuration fault. Reassures user it is not their fault and credits were refunded.
10ARTIFACT_EXPIREDInternal reasons artifact_expired, channel_expiredUpstream generated the video > 24h ago and its signed download URL expired before R2 persistence could complete. Credits refunded.
11UNKNOWNFallback when no pattern matches (classify() never guesses)Generic generation failure with credit refund confirmation.

14-Locale Error Mapping & Build Verification

  • Every FailCode in CODES has a corresponding localized message under fail.<CODE> across all 14 locale dictionary files (locales/<locale>/errors.json / compiled into messages.json).
  • GET /api/video/status/:id and GET /api/generate/status/:batchId always return failCode on both newly failed and already-settled failed rows (so refreshing the page preserves the specific actionable guidance instead of degrading to a generic error).
  • tests/server/fail-reason.test.ts enforces that every FailCode in CODES has non-empty translations in all 14 supported locales.

2. Channel Fault Attribution (server/src/channelFault.ts)

While failReason.ts maps ModelNotOpen and Arrearage to UPSTREAM_ERROR for the end user (because the user cannot fix our cloud account), operators need ModelNotOpen separated from ordinary 500 glitches immediately.

faultKind({ status, text }) classifies every upstream failure into one of three categories:

flowchart TD
    A["Upstream Error (HTTP status + body text)"] --> B{"Matches CONFIG_PATTERNS or HTTP 401/403?"}
    B -- "Yes (ModelNotOpen, Arrearage, InvalidApiKey)" --> C["FaultKind: config"]
    B -- "No" --> D{"HTTP 429 / 5xx or TRANSIENT_PATTERNS or pre-send DNS/Conn error?"}
    D -- "Yes" --> E["FaultKind: transient"]
    D -- "No (4xx content/param or Timeout)" --> F["FaultKind: permanent"]
    C --> G["Never Retry + Trigger reportConfigFault() Resend Alert"]
    E --> H["safeToRetry() = true (only if no artifact billed)"]
    F --> I["Never Retry + Refund User + Log failCode"]

Safe-to-Retry Contract (safeToRetry)

safeToRetry({ status, text }) returns true only when it is guaranteed that the upstream channel did not start generating or billing an artifact:

  1. faultKind is not "config".
  2. Upstream returned an explicit HTTP 429 or 500..599 error response, or the request failed at the pre-send connection layer (status === 0 with ECONNREFUSED, ENOTFOUND, EAI_AGAIN, ERR_INVALID_URL).
  3. Why ECONNRESET, socket hang up, and AbortError/TimeoutError are NEVER retried:
    • Those errors occur after the HTTP request payload has already been sent to Volcengine Ark or DashScope.
    • Because image generation APIs lack idempotency keys, retrying a timed-out or reset connection will generate and pay for a second image upstream.

Structured Upstream Diagnostics (parseUpstreamError)

Whenever an upstream call fails, parseUpstreamError(text, headers) extracts:

  • code (up to 80 chars from JSON error.code or code)
  • message (up to 300 chars from JSON error.message or message)
  • requestId (up to 80 chars from response headers in priority order: x-request-id -> x-tt-logid -> x-dashscope-request-id -> cf-ray)

These fields are logged in [gen] event=model_failed (errCode, req, http, fault) so operators can correlate failures directly with Volcengine or Alibaba support tickets without guessing from truncated error strings.

On this page