# HTTP status errors

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