Technical docs for Xuda Slim and Xuda CLI

Statuses the router returns to browsers and external clients. Source: config.json http_error_codes and cpi/router_module/index.mjs.

401 Unauthorized

Severity: error · HTTP: 401 · Category: auth

The page or API requires authentication that was missing, invalid, or expired.

Common causes

• Not signed in
• Missing/expired gtp_token or app token
• App is not publicly available

Resolution

1. Sign in and retry
2. Refresh the session token
3. Confirm the app/page is meant to be public

Auto-fix: none · User-actionable: yes · Related: -401

Source: router_module/site_unauthorized ~1020

403 Access Denied

Severity: error · HTTP: 403 · Category: auth

Authenticated, but the user is not authorized for this app or resource.

Common causes

• User lacks a role/permission
• Not a team member
• Plan/entitlement gate

Resolution

1. Request access from the app owner
2. Verify team membership/role
3. Check plan entitlement

Auto-fix: none · User-actionable: yes · Related: -403

Source: router_module mapping ~2911 (from -403)

404 Page not found

Severity: error · HTTP: 404 · Category: routing

The requested route, app, or resource does not exist.

Common causes

• Mistyped URL
• App/resource deleted or renamed
• Resource never existed

Resolution

1. Check the URL
2. Confirm the resource still exists
3. Recreate or update the link

Auto-fix: none · User-actionable: yes · Related: -404

Source: router_module/not_found ~1119

408 Session timeout

Severity: warning · HTTP: 408 · Category: session

The session timed out or was terminated by the operator.

Common causes

• Idle session expired
• Operator terminated the session

Resolution

1. Sign in again
2. Reload the page

Auto-fix: none · User-actionable: yes

Source: config.json http_error_codes

422 Unprocessable Entity

Severity: error · HTTP: 422 · Category: validation

Field validation failed. Body: { code:-1, error:"invalid_fields", fields:[...] }.

Common causes

• Invalid/missing fields
• Value out of allowed range or format

Resolution

1. Inspect the fields array
2. Correct the listed fields and resubmit

Auto-fix: none · User-actionable: yes · Related: -400

Source: router_module res.status(422) ~2802 (from -400)

423 Site Locked

Severity: info · HTTP: 423 · Category: deployment

The app deployment is currently building/updating; the page is temporarily locked.

Common causes

• A build/deploy is in progress

Resolution

1. Wait for the build to finish
2. Refresh the page shortly

Auto-fix: none · User-actionable: no · Related: 425

Source: router_module/site_locked ~1133

425 Site not ready

Severity: info · HTTP: 425 · Category: deployment

The deployment has not started/finished installing yet (too early to serve).

Common causes

• Install/provision not yet complete

Resolution

1. Wait for provisioning to complete
2. Refresh shortly

Auto-fix: none · User-actionable: no · Related: 423

Source: router_module/site_too_early ~1130

429 Too Many Requests

Severity: warning · HTTP: 429 · Category: rate-limit

Rate limit exceeded. Body: { code:-1, error:"rate_limited" }.

Common causes

• Too many requests in the window (e.g. 5 contact-form posts / 15 min)
• Brute-force protection

Resolution

1. Wait for the window to reset and retry
2. Reduce request frequency

Auto-fix: none · User-actionable: yes

Source: router_module rate limiter ~163

500 Internal Server Error

Severity: error · HTTP: 500 · Category: server

Generic fallback for an unmapped negative code or an unexpected server error.

Common causes

• Unhandled exception
• Negative code with no specific HTTP mapping

Resolution

1. Retry
2. Check server logs (xuda_logs)
3. Escalate if persistent

Auto-fix: none · User-actionable: no

Source: router_module mapping default ~2912

502 Bad Gateway

Severity: error · HTTP: 502 · Category: server

The upstream/proxy connection failed.

Common causes

• Upstream app process down
• Proxy could not connect

Resolution

1. Retry
2. Confirm the app process is running
3. Check upstream health

Auto-fix: none · User-actionable: no · Related: 503

Source: router_module proxy path ~2989

503 Site Off

Severity: warning · HTTP: 503 · Category: server

The app is offline.

Common causes

• App turned off
• Suspended/terminated account

Resolution

1. Turn the app back on
2. Resolve any account hold/suspension

Auto-fix: none · User-actionable: no

Source: router_module/site_off ~1126