# CPI Error Codes and Troubleshooting

Reference for the Xuda CPI server error codes. Every CPI method returns a `{ code, data }` envelope: a positive `code` means success and a negative `code` means an error. This guide explains the conventions, the HTTP status mapping, and how to resolve each documented code.

## How CPI errors work

### Response shape

Every CPI method returns `{ code: <number>, data: <value> }`. `code >= 1` is success; `code < 0` is an error. The shared client `axios_ajax()` returns `data` on success and throws `response.data` on error.

### Named string error keys

Some HTTP-layer errors add a string `error` key in addition to numeric `code`: `error: "rate_limited" | "invalid_fields" | "appeal_failed"`, with an optional `fields: []` array for validation failures.

### Internal → HTTP mapping

The router maps a few internal codes to HTTP statuses: `{ "-404": 404, "-403": 403, "-400": 422 }`. Every other negative code falls through to HTTP 500.

### Codes are context-dependent

The same number is reused across methods with different meanings (especially `-1` and `-400`). Always read the accompanying `data` message and the originating method; the meanings below are the common case, not a guarantee.

## Error groups

- [HTTP status errors](http-errors.md) - Browser and external-client facing statuses (401, 403, 404, 422, 423, 425, 429, 500, 502, 503).
- [Client-contract codes](client-contracts.md) - Codes the dashboard reacts to with specific UX (billing, auth redirect, file conflicts, timeouts).
- [CPI negative codes](cpi-codes.md) - The common negative codes returned across the cpi modules, with typical meanings.
- [Internal / undeclared errors](internal-errors.md) - Errors detected by shape or source that bypass the envelope (uncaught exceptions, broker failures, anomalies).
- [By module (full reference)](by-module.md) - Exhaustive, source-derived list of every negative code each cpi module returns, with its messages.

## At a glance

- **Group A - HTTP status errors:** 11 codes
- **Group B - Client-contract codes:** 7 codes
- **Group C - API envelope conventions:** 4 conventions
- **Group D - CPI negative codes:** 26 codes
- **Group E - Internal / undeclared errors:** 8 codes