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:
| Priority | FailCode | Upstream Match Patterns / Internal Reasons | User Guidance & Self-Recovery |
|---|---|---|---|
1 | INPUT_PRIVACY | InputImageSensitiveContentDetected.PrivacyInformation | Uploaded 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). |
2 | INPUT_SENSITIVE | InputImageSensitiveContentDetected, 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. |
3 | OUTPUT_SENSITIVE | Output data may contain inappropriate content, green net check / 绿网, Output(Image|Video)SensitiveContentDetected, OutputDataInspectionFailed, DataInspectionFailed | Generated output triggered content safety / Green Net filter. User should soften prompt wording or try another image. |
4 | PROMPT_SENSITIVE | InputTextSensitiveContentDetected, InputTextDataInspection, prompt.*(sensitive|blocked), 内容审核.*输入 | Text prompt triggered safety filter. User should revise prompt text. |
5 | IP_RISK | IPInfringement, Copyright(Suspect|Infringement), TrademarkSuspect, PortraitRight | DashScope copyright, trademark, or portrait-right block. Remove brand names or celebrity references. |
6 | PARAM_UNSUPPORTED | duration 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. |
7 | BUSY | Throttling, RequestLimitExceeded, RequestsRateLimitExceeded, TooManyRequests, rate limit, ARK_HTTP_429, DS_HTTP_429, ConcurrentRequestsExceeded | Upstream provider rate-limited or queue congested. Credits refunded; retry shortly. |
8 | TIMEOUT | AbortError, TimeoutError, ETIMEDOUT, ERR_TIMEOUT, DS_TASK_TIMEOUT, aborted due to timeout, or internal reason exceeded_max_age | Upstream request or async task exceeded timeout (120s image / 6h video / 10m image sweeper). Credits refunded. |
9 | UPSTREAM_ERROR | ECONNRESET, 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_url | Provider service error, network failure, or account configuration fault. Reassures user it is not their fault and credits were refunded. |
10 | ARTIFACT_EXPIRED | Internal reasons artifact_expired, channel_expired | Upstream generated the video > 24h ago and its signed download URL expired before R2 persistence could complete. Credits refunded. |
11 | UNKNOWN | Fallback when no pattern matches (classify() never guesses) | Generic generation failure with credit refund confirmation. |
14-Locale Error Mapping & Build Verification
- Every
FailCodeinCODEShas a corresponding localized message underfail.<CODE>across all14locale dictionary files (locales/<locale>/errors.json/ compiled intomessages.json). GET /api/video/status/:idandGET /api/generate/status/:batchIdalways returnfailCodeon both newly failed and already-settledfailedrows (so refreshing the page preserves the specific actionable guidance instead of degrading to a generic error).tests/server/fail-reason.test.tsenforces that everyFailCodeinCODEShas 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:
faultKindis not"config".- Upstream returned an explicit HTTP
429or500..599error response, or the request failed at the pre-send connection layer (status === 0withECONNREFUSED,ENOTFOUND,EAI_AGAIN,ERR_INVALID_URL). - Why
ECONNRESET,socket hang up, andAbortError/TimeoutErrorare 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 to80chars from JSONerror.codeorcode)message(up to300chars from JSONerror.messageormessage)requestId(up to80chars 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.
Video Generation, Polling & Atomic Settlement
Two-phase async video pipeline, portrait bridge, browser polling vs. 5-minute Cron sweeper, atomic conditional settlement, and 24-hour signed URL expiry rules.
Spending Safeguards, Worker Crons & Ops Alerts
Tiered daily video spending caps for paid vs. unpaid users, runtime app_settings switches, Worker Cron schedules, and 6-hour cooldown Resend alerts.