Cubicles docs
Errors
Every error is application/problem+json with a stable code: branch on it, not on title.
Shape
{
"type": "https://cubicles.cloud/docs/errors/desktop_not_running",
"title": "The desktop isn't running.",
"status": 409,
"instance": "/api/v1/desktops/d0000000-…/exec",
"code": "desktop_not_running"
}detail is added when there's a hint ("3 attempts left."), and fieldErrors, a list of { field, message }, for field problems. A 429 carries Retry-After in seconds.
Codes
| Status | Code | Meaning |
|---|---|---|
| 400 | validation_failed | Invalid fields, or a body that isn't valid JSON (fieldErrors says which) |
| 400 | confirm_name_mismatch | The typed name isn't the desktop's |
| 400 | plan_unavailable | Unknown or retired plan (also os_unavailable, region_unavailable) |
| 401 | unauthenticated | No API key or session, whatever the method |
| 401 | invalid_api_key | Wrong, expired or deleted API key |
| 403 | forbidden | A signed-in browser request (or any /auth/… call) without its CSRF header |
| 403 | session_required | Managing API keys, the billing portal or the admin dashboard with an API key |
| 403 | api_key_required | /mcp with a browser session instead of an API key |
| 404 | not_found | No such route (checked before the key), or not yours |
| 404 | share_not_found | Unknown or ended share link |
| 405 | method_not_allowed | The endpoint doesn't take that method (see Allow) |
| 409 | name_taken | Desktop name already in use in that region |
| 409 | plan_sold_out | No server has room for that plan right now |
| 400 | free_plan_unavailable | free with a plan other than the free one, or an OS with a fee |
| 409 | too_many_desktops | The account already has its free desktop |
| 409 | action_not_allowed | Not offered in the current status (see allowedActions) |
| 409 | desktop_not_running | A command, file, screenshot or stream needs a running desktop |
| 409 | subscription_active | Deleting a desktop needs its subscription canceled first |
| 409 | too_many_shares | The desktop has 20 shares that haven't ended |
| 409 | desktop_unavailable | An agent can't be set up on that desktop |
| 409 | agent_exists | The desktop already has an agent of that harness |
| 409 | too_many_agents | The account has 20 agents |
| 409 | too_many_api_keys | The account has 25 API keys |
| 409 | agent_unreachable | The desktop didn't answer |
| 410 | share_expired | Share link past its time |
| 403 | folder_not_readable | The desktop's user can't read the folder to list |
| 403 | file_not_readable | The desktop's user can't read the file to download |
| 404 | folder_not_found | No folder to list at that path |
| 404 | file_not_found | No file to download at that path |
| 413 | file_too_large | An upload or download over 100 MB |
| 423 | account_closed | The account is closed |
| 429 | too_many_attempts | Rate limit hit; wait the Retry-After header's seconds |
| 429 | desktop_busy | Too many commands at once on one desktop; wait the Retry-After header's seconds |
| 500 | internal_error | Unexpected server error |
| 502 | desktop_unreachable | The desktop didn't answer a command or screenshot |
| 502 | upload_failed | The desktop didn't take an uploaded file |
| 502 | payment_provider_error | The payment provider refused or failed a request |
| 503 | server_busy | A desktop's server had no room for another command in time; see Retry-After |