docs: add error codes reference page

docs.json

@@ -360,6 +360,7 @@
                 "pages": [
                   "/phala-cloud/references/overview",
                   "/phala-cloud/references/performance-report",
+                  "/phala-cloud/references/error-codes",
                   {
                     "group": "Phala Cloud API",
                     "pages": [

phala-cloud/networking/troubleshooting.mdx

@@ -302,4 +302,6 @@ When reporting issues, provide:
 4. **Container logs**: `docker logs <container> --tail 100`
 5. **Test results** from debugging commands above
 
+For API error codes like `ERR-01-xxx`, see the [Error Codes Reference](/phala-cloud/references/error-codes).
+
 The more specific information you provide, the faster issues can be resolved.

phala-cloud/phala-cloud-api/overview.mdx

@@ -12,3 +12,7 @@ You can use the API to access all the features available on the Phala Cloud plat
 
 You may want to check our Cloud API example that shows the basic operations like creating and manage a CVM here: [https://github.com/Leechael/phala-cloud-api-example](https://github.com/Leechael/phala-cloud-api-example)
 
+## Error Handling
+
+API errors return structured error codes in the format `ERR-{MODULE}-{CODE}`. See the [Error Codes Reference](/phala-cloud/references/error-codes) for a complete list of error codes and their meanings.
+

phala-cloud/phala-cloud-cli/ci-cd-automation/setup-a-ci-cd-pipeline.mdx

@@ -103,6 +103,6 @@ phala cvms get my-tee-app
 
 **Build failures**: Ensure your Dockerfile builds locally with `docker build .`
 
-**Deploy failures**: Check that `docker-compose.yml` is valid and the image path matches your registry.
+**Deploy failures**: Check that `docker-compose.yml` is valid and the image path matches your registry. For API error codes like `ERR-01-xxx`, see the [Error Codes Reference](/phala-cloud/references/error-codes).
 
 **Debug locally**: Use [act](https://github.com/nektos/act) to run GitHub Actions locally with a `.env` file containing your secrets.

phala-cloud/references/error-codes.mdx

@@ -0,0 +1,80 @@
+---
+title: Error Codes
+description: Reference for Phala Cloud API error codes
+---
+# Error Code Catalog
+
+This document lists all error codes used by Phala Cloud API.
+
+Error codes follow the format `ERR-{MODULE}-{CODE}` where:
+- **MODULE**: Two-digit module identifier (01, 02, 03, ...)
+- **CODE**: Three-digit sequential error number within the module
+
+## Modules
+
+- **Module 01** - CVM API / Preflight
+- **Module 02** - Inventory
+- **Module 03** - CVM Operations
+- **Module 04** - Workspace
+
+---
+
+## Module 01: CVM API / Preflight
+
+
+| Error Code | Exception Class | Message |
+|------------|----------------|---------|
+| `ERR-01-001` | `NodeNotFoundError` | The requested node is not available<br/>*Raised when specified node is not found* |
+| `ERR-01-002` | `ComposeFileRequiredError` | The request contains invalid parameters<br/>*Raised when compose_file is required but not provided* |
+| `ERR-01-003` | `InvalidComposeFileError` | The Docker Compose file contains errors<br/>*Raised when Docker Compose file is invalid* |
+| `ERR-01-004` | `DuplicateCvmNameError` | (dynamic: A CVM with name '...)<br/>*Raised when a CVM name already exists in the workspace (HTTP 409)* |
+| `ERR-01-005` | `HashRegistrationRequired` | Compose hash registration required on-chain<br/>*Raised when compose hash needs to be registered on-chain (HTTP 465)* |
+| `ERR-01-006` | `HashInvalidOrExpired` | The provided compose hash is invalid or has expired<br/>*Raised when compose hash is invalid or expired (HTTP 466)* |
+| `ERR-01-007` | `TxVerificationFailed` | Transaction verification failed<br/>*Raised when transaction verification fails (HTTP 467)* |
+| `ERR-01-008` | `HashNotAllowed` | The compose hash is not allowed by the on-chain contract<br/>*Raised when compose hash is not allowed by the contract (HTTP 468)* |
+
+
+## Module 02: Inventory
+
+
+| Error Code | Exception Class | Message |
+|------------|----------------|---------|
+| `ERR-02-001` | `InstanceTypeNotFoundError` | The requested instance type does not exist<br/>*Raised when a requested instance type is not found.* |
+| `ERR-02-002` | `ResourceNotAvailableError` | No available resources match your requirements<br/>*Raised when no suitable resources are found* |
+| `ERR-02-003` | `InsufficientVcpuError` | The selected node does not have enough CPU capacity<br/>*Raised when teepod has insufficient vCPU resources.* |
+| `ERR-02-004` | `InsufficientMemoryError` | The selected node does not have enough memory<br/>*Raised when teepod has insufficient memory resources.* |
+| `ERR-02-005` | `InsufficientSlotsError` | The selected node has reached its maximum capacity<br/>*Raised when teepod has no available CVM slots.* |
+| `ERR-02-006` | `GpuAllocationError` | The selected node does not have enough GPU resources<br/>*Raised when GPU allocation fails* |
+| `ERR-02-007` | `InsufficientGpuError` | The selected node does not have enough GPU resources<br/>*Raised when teepod has insufficient GPU resources.* |
+| `ERR-02-008` | `InvalidRequestError` | The request contains invalid parameters<br/>*Raised when request parameters are invalid* |
+| `ERR-02-009` | `IncompatibleConfigurationError` | The configuration parameters are not compatible with each other<br/>*Raised when resource configuration is not compatible* |
+| `ERR-02-010` | `ImageNotFoundError` | The requested operating system image is not available<br/>*Raised when a requested OS image is not found.* |
+| `ERR-02-011` | `KmsNotFoundError` | The requested security configuration is not available on this node<br/>*Raised when no matching KMS is found on teepod.* |
+| `ERR-02-012` | `TeepodNotAccessibleError` | The requested node is not available<br/>*Raised when user doesn't have permission to access a teepod.* |
+| `ERR-02-013` | `OsImageNotCompatibleError` | The requested operating system image is not available<br/>*Raised when no compatible OS image is found.* |
+| `ERR-02-014` | `NodeCapacityNotConfiguredError` | The requested node is not available<br/>*Raised when node capacity is not properly configured.* |
+| `ERR-02-015` | `QuotaExceededError` | Your account has reached its resource quota<br/>*Raised when team resource quota would be exceeded.* |
+
+
+## Module 03: CVM Operations
+
+
+| Error Code | Exception Class | Message |
+|------------|----------------|---------|
+| `ERR-03-001` | `CvmNotFoundError` | The requested CVM was not found<br/>*Raised when a CVM is not found by the given identifier.* |
+| `ERR-03-002` | `MultipleCvmsWithSameNameError` | Multiple CVMs have the same name in this workspace<br/>*Raised when multiple CVMs share the same name in a workspace.* |
+| `ERR-03-005` | `CvmAccessDeniedError` | The requested CVM was not found<br/>*Raised when user lacks permission for CVM operation.* |
+
+
+## Module 04: Workspace
+
+
+| Error Code | Exception Class | Message |
+|------------|----------------|---------|
+| `ERR-04-001` | `InsufficientBalanceError` | Your account balance is too low to create new resources<br/>*Raised when account balance is too low* |
+| `ERR-04-002` | `MaxCvmLimitError` | Your account has reached the maximum number of instances<br/>*Raised when VM count limit is reached* |
+| `ERR-04-003` | `ResourceLimitExceededError` | The requested resources exceed your account limits<br/>*Raised when resource limits are exceeded* |
+
+
+---
+

phala-cloud/references/overview.mdx

@@ -11,6 +11,10 @@ Welcome to the Phala Cloud References section. This comprehensive documentation
 
 The Phala Cloud CLI (`phala`) is your primary tool for managing deployments and interacting with the platform from the command line.
 
+### 🚨 Error Codes
+
+The [Error Codes Reference](/phala-cloud/references/error-codes) documents all API error codes with their meanings. Useful for debugging deployment failures and API integration issues.
+
 ### 📊 Performance Reports
 
 Comprehensive performance analysis of Phala Cloud's TEE infrastructure, including:

phala-cloud/references/phala-cloud-cli/phala/deploy.mdx

@@ -107,3 +107,7 @@ phala deploy --kms-id ethereum --private-key <key> --rpc-url <url>
 phala deploy --node-id 6
 ```
 
+### Error Codes
+
+If deployment fails with an error code like `ERR-01-xxx` or `ERR-02-xxx`, see the [Error Codes Reference](/phala-cloud/references/error-codes) for details.
+

phala-cloud/troubleshooting/troubleshooting.mdx

@@ -160,6 +160,10 @@ See [GPU TEE Billing](/phala-cloud/pricing#gpu-tee-billing-rules) for details on
 - When billing starts (only on launch)
 - Commitment pricing options
 
+## API Error Codes
+
+If you encounter API errors with codes like `ERR-01-xxx` or `ERR-02-xxx`, see the [Error Codes Reference](/phala-cloud/references/error-codes) for a complete list of error codes and their meanings.
+
 ## Still Need Help?
 
 - Join our [Global Telegram](https://t.me/+nbhjx1ADG9EyYmI9)

scripts/convert-error-codes.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# Convert error-codes.md from phala-cloud-monorepo to MDX format
+# Usage: ./scripts/convert-error-codes.sh
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(dirname "$SCRIPT_DIR")"
+SOURCE_FILE="$REPO_ROOT/../phala-cloud-monorepo/docs/error-codes.md"
+OUTPUT_FILE="$REPO_ROOT/phala-cloud/references/error-codes.mdx"
+
+if [ ! -f "$SOURCE_FILE" ]; then
+    echo "Error: Source file not found at $SOURCE_FILE"
+    exit 1
+fi
+
+# Create output directory if needed
+mkdir -p "$(dirname "$OUTPUT_FILE")"
+
+# Generate MDX with frontmatter
+{
+    # Add frontmatter
+    cat <<'FRONTMATTER'
+---
+title: Error Codes
+description: Reference for Phala Cloud API error codes
+---
+FRONTMATTER
+
+    # Process source file:
+    # 1. Remove **Source:** lines
+    # 2. Remove "Adding New Errors" section and everything after
+    # 3. Remove teehouse module path references (internal implementation details)
+    # 4. Remove -000 errors (base class exceptions, not user-facing)
+    sed -n '1,/^## Adding New Errors/{ /^## Adding New Errors/d; /^\*\*Source:\*\*/d; p }' "$SOURCE_FILE" \
+        | sed 's/ (`teehouse[^`]*`)//g' \
+        | grep -v 'ERR-[0-9][0-9]-000'
+
+} > "$OUTPUT_FILE"
+
+echo "Generated: $OUTPUT_FILE"