diff --git a/docs.json b/docs.json index 7a3dac60..6b5c4951 100644 --- a/docs.json +++ b/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": [ diff --git a/phala-cloud/networking/troubleshooting.mdx b/phala-cloud/networking/troubleshooting.mdx index 4371e766..e9723501 100644 --- a/phala-cloud/networking/troubleshooting.mdx +++ b/phala-cloud/networking/troubleshooting.mdx @@ -302,4 +302,6 @@ When reporting issues, provide: 4. **Container logs**: `docker logs --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. \ No newline at end of file diff --git a/phala-cloud/phala-cloud-api/overview.mdx b/phala-cloud/phala-cloud-api/overview.mdx index 7096cd0b..d0b89d0b 100644 --- a/phala-cloud/phala-cloud-api/overview.mdx +++ b/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. + diff --git a/phala-cloud/phala-cloud-cli/ci-cd-automation/setup-a-ci-cd-pipeline.mdx b/phala-cloud/phala-cloud-cli/ci-cd-automation/setup-a-ci-cd-pipeline.mdx index 186027f0..9c54b9a0 100644 --- a/phala-cloud/phala-cloud-cli/ci-cd-automation/setup-a-ci-cd-pipeline.mdx +++ b/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. diff --git a/phala-cloud/references/error-codes.mdx b/phala-cloud/references/error-codes.mdx new file mode 100644 index 00000000..b3e51833 --- /dev/null +++ b/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
*Raised when specified node is not found* | +| `ERR-01-002` | `ComposeFileRequiredError` | The request contains invalid parameters
*Raised when compose_file is required but not provided* | +| `ERR-01-003` | `InvalidComposeFileError` | The Docker Compose file contains errors
*Raised when Docker Compose file is invalid* | +| `ERR-01-004` | `DuplicateCvmNameError` | (dynamic: A CVM with name '...)
*Raised when a CVM name already exists in the workspace (HTTP 409)* | +| `ERR-01-005` | `HashRegistrationRequired` | Compose hash registration required on-chain
*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
*Raised when compose hash is invalid or expired (HTTP 466)* | +| `ERR-01-007` | `TxVerificationFailed` | Transaction verification failed
*Raised when transaction verification fails (HTTP 467)* | +| `ERR-01-008` | `HashNotAllowed` | The compose hash is not allowed by the on-chain contract
*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
*Raised when a requested instance type is not found.* | +| `ERR-02-002` | `ResourceNotAvailableError` | No available resources match your requirements
*Raised when no suitable resources are found* | +| `ERR-02-003` | `InsufficientVcpuError` | The selected node does not have enough CPU capacity
*Raised when teepod has insufficient vCPU resources.* | +| `ERR-02-004` | `InsufficientMemoryError` | The selected node does not have enough memory
*Raised when teepod has insufficient memory resources.* | +| `ERR-02-005` | `InsufficientSlotsError` | The selected node has reached its maximum capacity
*Raised when teepod has no available CVM slots.* | +| `ERR-02-006` | `GpuAllocationError` | The selected node does not have enough GPU resources
*Raised when GPU allocation fails* | +| `ERR-02-007` | `InsufficientGpuError` | The selected node does not have enough GPU resources
*Raised when teepod has insufficient GPU resources.* | +| `ERR-02-008` | `InvalidRequestError` | The request contains invalid parameters
*Raised when request parameters are invalid* | +| `ERR-02-009` | `IncompatibleConfigurationError` | The configuration parameters are not compatible with each other
*Raised when resource configuration is not compatible* | +| `ERR-02-010` | `ImageNotFoundError` | The requested operating system image is not available
*Raised when a requested OS image is not found.* | +| `ERR-02-011` | `KmsNotFoundError` | The requested security configuration is not available on this node
*Raised when no matching KMS is found on teepod.* | +| `ERR-02-012` | `TeepodNotAccessibleError` | The requested node is not available
*Raised when user doesn't have permission to access a teepod.* | +| `ERR-02-013` | `OsImageNotCompatibleError` | The requested operating system image is not available
*Raised when no compatible OS image is found.* | +| `ERR-02-014` | `NodeCapacityNotConfiguredError` | The requested node is not available
*Raised when node capacity is not properly configured.* | +| `ERR-02-015` | `QuotaExceededError` | Your account has reached its resource quota
*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
*Raised when a CVM is not found by the given identifier.* | +| `ERR-03-002` | `MultipleCvmsWithSameNameError` | Multiple CVMs have the same name in this workspace
*Raised when multiple CVMs share the same name in a workspace.* | +| `ERR-03-005` | `CvmAccessDeniedError` | The requested CVM was not found
*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
*Raised when account balance is too low* | +| `ERR-04-002` | `MaxCvmLimitError` | Your account has reached the maximum number of instances
*Raised when VM count limit is reached* | +| `ERR-04-003` | `ResourceLimitExceededError` | The requested resources exceed your account limits
*Raised when resource limits are exceeded* | + + +--- + diff --git a/phala-cloud/references/overview.mdx b/phala-cloud/references/overview.mdx index 6b93729e..aa839808 100644 --- a/phala-cloud/references/overview.mdx +++ b/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: diff --git a/phala-cloud/references/phala-cloud-cli/phala/deploy.mdx b/phala-cloud/references/phala-cloud-cli/phala/deploy.mdx index 0777ae95..d08ae6c5 100644 --- a/phala-cloud/references/phala-cloud-cli/phala/deploy.mdx +++ b/phala-cloud/references/phala-cloud-cli/phala/deploy.mdx @@ -107,3 +107,7 @@ phala deploy --kms-id ethereum --private-key --rpc-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. + diff --git a/phala-cloud/troubleshooting/troubleshooting.mdx b/phala-cloud/troubleshooting/troubleshooting.mdx index 9264c233..7f95962f 100644 --- a/phala-cloud/troubleshooting/troubleshooting.mdx +++ b/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) diff --git a/scripts/convert-error-codes.sh b/scripts/convert-error-codes.sh new file mode 100755 index 00000000..229b3860 --- /dev/null +++ b/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"