> ## Documentation Index
> Fetch the complete documentation index at: https://docs.phala.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Error Codes
> 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 05** - Credentials
* **Module 06** - Authentication (OAuth redirect errors — not returned as JSON API responses)
***
## 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 by an onchain KMS compose update when the new compose hash is not yet on DstackApp.allowedComposeHashes; the response carries commit\_token, commit\_url, and the on-chain action needed to complete the prepare-approve-commit flow (HTTP 465)* |
| `ERR-01-006` | `HashInvalidOrExpired` | The provided compose hash is invalid or has expired
*Raised at commit time when the commit token is unknown, has expired (14-day TTL), has been superseded by a newer prepare for the same CVM, or the compose hash bound to the token no longer matches the compose file currently saved for this CVM — re-run prepare to recover (HTTP 466)* |
| `ERR-01-007` | `TxVerificationFailed` | Transaction verification failed
*Raised at commit time when the supplied transaction\_hash cannot be verified against the expected addComposeHash state change — the receipt is missing, the transaction reverted, or it did not target the expected DstackApp contract (HTTP 467)* |
| `ERR-01-008` | `HashNotAllowed` | The compose hash is not allowed by the on-chain contract
*Raised at commit time when DstackApp.allowedComposeHashes(bytes32) returns false for the target hash — typically because the Phase 2 approval transaction has not actually landed on the expected contract, or landed on the wrong 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.* |
| `ERR-02-016` | `GpuDeviceInUseError` | GPUs are available but currently occupied at device level
*Raised when GPUs are available in database but occupied at device level.* |
## 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 (HTTP 404).* |
| `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-003` | `CvmNotInWorkspaceError` | No CVM found in this workspace
*Raised in admin contexts when a CVM exists but belongs to a different workspace — reveals the workspace mismatch (HTTP 404).* |
| `ERR-03-004` | `CvmNotInWorkspaceError` | The requested CVM was not found
*Raised in non-admin contexts when a CVM belongs to a different workspace — message matches ERR-03-001 to avoid leaking CVM existence (HTTP 404).* |
| `ERR-03-005` | `CvmAccessDeniedError` | The requested CVM was not found
*Raised when user lacks permission for a CVM operation — message intentionally matches ERR-03-001 to avoid revealing whether the CVM exists (HTTP 404).* |
| `ERR-03-006` | `ReplicaImageNotAvailableError` | The source CVM's OS image is not available on the target node
*Raised when the source CVM's OS image is not available on the target node.* |
| `ERR-03-007` | `CvmAppIdConflictError` | This app\_id already has an active CVM with a different configuration. Provision again to get a new app\_id, or use the existing CVM.
*Raised when app\_id is already used by a different configuration in the same workspace (HTTP 409).* |
| `ERR-03-008` | `ReplicaSourceInstanceNotAccessibleError` | The source CVM instance was not found in this workspace or access is denied
*Raised when the replica source CVM instance is not visible in the current workspace (HTTP 404).* |
| `ERR-03-009` | `ReplicaComposeHashRequiredError` | This app has multiple live CVM instances. Please specify compose\_hash to choose which revision to replicate.
*Raised when replicate needs an explicit compose\_hash due to multiple live instances.* |
| `ERR-03-010` | `MultipleCvmsForIdentifierError` | Multiple CVMs match this identifier in the workspace
*Raised when an identifier (e.g. app\_id) matches multiple CVMs in a workspace.* |
## Module 04: Workspace
| Error Code | Exception Class | Message |
| ------------ | ---------------------------- | ----------------------------------------------------------------------------------------------------- |
| `ERR-04-001` | `InsufficientBalanceError` | You need to top up your account before launching a CVM.
*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* |
## Module 05: Credentials
| Error Code | Exception Class | Message |
| ------------ | ------------------------- | ---------------------------------------------------------------------------------------------------- |
| `ERR-05-001` | `TokenLimitExceededError` | (dynamic: You have reached the maximum of ...)
*Raised when workspace token limit is exceeded* |
| `ERR-05-002` | `TokenRateLimitError` | (dynamic: Rate limit exceeded: maximum ...)
*Raised when token creation rate limit is exceeded* |
***