Xuda logo

xuda.io

Technical docs for Xuda Slim and Xuda CLI

 Product overview
Troubleshooting

CPI negative codes

The common negative codes returned across the cpi modules. The same number is reused across methods, so always read the accompanying data message and the originating method.

Troubleshooting pages

CPI server error codes, the HTTP mapping, and how to resolve each one.

CPI Error Codes and Troubleshooting HTTP status errors Client-contract codes CPI negative codes Internal and undeclared errors CPI error codes by module
Docs page
Raw markdown xuda.io

The common negative codes returned across the cpi modules. The same number is reused across methods, so always read the accompanying data message and the originating method.

-1 Generic failure

Severity: error · HTTP: 500 · Category: generic

The catch-all error. Meaning depends entirely on the data message and the method.

Common causes

  • Not found
  • Unauthorized
  • Missing/invalid input
  • Duplicate contact
  • Invalid ssh key
  • Caught exception (err.message)

Resolution

  1. Read the data message
  2. Identify the calling method
  3. Fix the specific condition the message describes

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

Source: nearly all modules (most common code)

-400 Bad request / validation

Severity: error · HTTP: 422 · Category: validation

Input validation failed or a required parameter was missing/malformed. Maps to HTTP 422.

Common causes

  • Missing required parameter
  • Wrong type/shape (e.g. expected Array)
  • Value out of range

Resolution

  1. Validate the request payload against the method contract
  2. Correct and resubmit

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

Source: nearly all modules (2nd most common)

-402 Stripe / billing error

Severity: error · Category: billing

A Stripe or billing operation failed (customer, charge, subscription, schedule, product).

Common causes

  • Stripe customer not found
  • Charge not captured
  • Price/product not configured
  • Subscription/schedule create failed

Resolution

  1. Check the Stripe customer/product config
  2. Inspect the data message
  3. Verify Stripe keys/config

Auto-fix: none · User-actionable: yes · Related: -90, -91, -93

Source: stripe_module, domains_module

-403 Forbidden

Severity: error · HTTP: 403 · Category: auth

The action is not allowed for this user/context. Maps to HTTP 403.

Common causes

  • Marketplace pro required (approved seller or ambassador)
  • Invalid appeal token
  • Permission denied

Resolution

  1. Confirm the required entitlement/role
  2. Read the data message for the specific gate

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

Source: marketplace_module, session_module

-404 Not found

Severity: error · HTTP: 404 · Category: routing

The target resource does not exist. Maps to HTTP 404.

Common causes

  • account_not_found
  • item not found
  • invalid_profile
  • target_not_found / target_unavailable
  • widget_disabled

Resolution

  1. Confirm the id/target exists
  2. Read the data message for which resource

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

Source: ai_module, marketplace_module

-451 DB get failed

Severity: error · Category: database

Reading a CouchDB document failed.

Common causes

  • Document missing
  • CouchDB unavailable/error

Resolution

  1. Check CouchDB availability
  2. Verify the doc id exists

Auto-fix: none · User-actionable: no · Related: -460, -462, -870

Source: db_module ~104

-460 DB save/delete failed

Severity: error · Category: database

Saving or deleting a CouchDB document failed (after conflict retries).

Common causes

  • Write conflict that exhausted retries
  • CouchDB unavailable/error

Resolution

  1. Retry
  2. Check CouchDB health
  3. Inspect the data message

Auto-fix: retry · User-actionable: no · Related: -451, -462

Source: db_module ~122/180/1508

-462 DB error / missing parameter

Severity: error · Category: database

A database helper failed or a required parameter (e.g. app_id) was missing.

Common causes

  • app_id required
  • CouchDB error (err.message)

Resolution

  1. Provide the missing parameter
  2. Check CouchDB health

Auto-fix: none · User-actionable: no · Related: -451, -460

Source: db_module ~572/620

-870 DB view / firewall error

Severity: error · Category: database

A CouchDB view query failed, or a firewall/data check rejected the request.

Common causes

  • View query error
  • Firewall/data rule rejection

Resolution

  1. Check the view/design doc
  2. Inspect the data message

Auto-fix: none · User-actionable: no

Source: db_module ~190, app_module

-200 File operation error

Severity: error · Category: drive

A drive/file operation failed.

Common causes

  • Filesystem error
  • Invalid file operation/input

Resolution

  1. Inspect the data message
  2. Verify the file/path and operation

Auto-fix: none · User-actionable: no · Related: -762, -764

Source: drive_module (several), plugins_module

-762 File error

Severity: error · Category: drive

A specific file error (e.g. file already exists at a lower-level check).

Common causes

  • File already exists
  • File error

Resolution

  1. Inspect the data message
  2. Resolve the file conflict

Auto-fix: none · User-actionable: yes · Related: -764, -200

Source: drive_module ~1251

-1310 Account-info validation error

Severity: error · Category: account

Account information failed validation on update.

Common causes

  • Invalid account field values

Resolution

  1. Inspect which fields failed
  2. Correct and resubmit

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

Source: account_module

-55 Team operation failed

Severity: error · Category: team

A team-level operation failed.

Common causes

  • Team op error

Resolution

  1. Inspect the data message
  2. Verify team state

Auto-fix: none · User-actionable: no · Related: -56, -57

Source: team_module, account_module

-56 Member operation failed

Severity: error · Category: team

A team-member operation failed.

Common causes

  • Member op error

Resolution

  1. Inspect the data message
  2. Verify member state

Auto-fix: none · User-actionable: no · Related: -55, -57

Source: team_module, account_module

-57 Access operation failed

Severity: error · Category: team

A team access/permission operation failed.

Common causes

  • Access op error

Resolution

  1. Inspect the data message
  2. Verify access/permission state

Auto-fix: none · User-actionable: no · Related: -55, -56

Source: team_module, account_module

-10 Missing required field

Severity: error · Category: validation

A required field was missing (e.g. "Missing email").

Common causes

  • Required field absent from the request

Resolution

  1. Add the missing field and resubmit

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

Source: router_module signup ~3209/3308, others

-20 Email malformed

Severity: error · Category: validation

The provided email failed format validation.

Common causes

  • Invalid email format

Resolution

  1. Provide a valid email address

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

Source: router_module signup ~3213/3312

-30 Password validation failed

Severity: error · Category: validation

The password did not meet validation requirements (data carries details).

Common causes

  • Weak/invalid password

Resolution

  1. Read the validation detail in data
  2. Choose a compliant password

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

Source: router_module signup ~3221/3361

-50 Account/token conflict

Severity: error · Category: account

Signup conflict: "User already exist" or "Token not found".

Common causes

  • Account already exists
  • Verification token not found

Resolution

  1. Sign in instead
  2. Request a fresh verification token

Auto-fix: none · User-actionable: yes

Source: router_module signup ~3230/3370

-60 Store account problem

Severity: error · Category: account

Persisting the account during signup failed.

Common causes

  • Account store/save failure

Resolution

  1. Retry
  2. Check account/db health

Auto-fix: retry · User-actionable: no · Related: -460

Source: router_module signup ~3110/3263/3382

-33 Region/datacenter not found

Severity: error · Category: deployment

A deploy operation could not find the requested region/datacenter.

Common causes

  • vps region not found
  • datacenter/region misconfigured

Resolution

  1. Verify the region/datacenter id
  2. Check deploy config

Auto-fix: none · User-actionable: no

Source: deploy_module

-500 Controller error

Severity: error · HTTP: 500 · Category: server

A controller-level operation threw (err.message).

Common causes

  • Unexpected controller exception

Resolution

  1. Inspect the data message and server logs

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

Source: controller_module

-32000 JSON-RPC server error

Severity: error · Category: mcp

A generic JSON-RPC server error from the MCP layer (reserved JSON-RPC range).

Common causes

  • MCP request handling failed

Resolution

  1. Inspect the MCP request and data message

Auto-fix: none · User-actionable: no

Source: mcp_module

-88 Module operation error (generic)

Severity: error · Category: generic

A module-local caught exception (err.message). Used by several modules.

Common causes

  • Caught exception in the calling method

Resolution

  1. Read the data message
  2. Identify the calling method

Auto-fix: none · User-actionable: no · Related: -1, -111, -112

Source: app_module, deploy_module, backup_module, session_module, ws_dashboard_module, http_module

-111 Module operation error (generic)

Severity: error · Category: generic

A module-local caught exception (err.message). Used by several modules.

Common causes

  • Caught exception in the calling method

Resolution

  1. Read the data message
  2. Identify the calling method

Auto-fix: none · User-actionable: no · Related: -1, -88, -112

Source: ai_module, notification_module, ws_dashboard_module

-112 DB/deploy operation error (generic)

Severity: error · Category: generic

A db/deploy module caught exception (err.message).

Common causes

  • Caught exception in a db/deploy method

Resolution

  1. Read the data message
  2. Check db/deploy health

Auto-fix: none · User-actionable: no · Related: -1, -88, -111

Source: db_module ~440, deploy_module

Beyond the codes above, individual modules use small negative codes (e.g. -2 … -25, -44/-45/-46, -64 … -78, -99/-101/-106) for module-specific intermediate states. These are almost always paired with a descriptive data message (often err.message). When you hit one, read the data string and the originating method rather than relying on the number alone.