Cubicles
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

StatusCodeMeaning
400validation_failedInvalid fields, or a body that isn't valid JSON (fieldErrors says which)
400confirm_name_mismatchThe typed name isn't the desktop's
400plan_unavailableUnknown or retired plan (also os_unavailable, region_unavailable)
401unauthenticatedNo API key or session, whatever the method
401invalid_api_keyWrong, expired or deleted API key
403forbiddenA signed-in browser request (or any /auth/… call) without its CSRF header
403session_requiredManaging API keys, the billing portal or the admin dashboard with an API key
403api_key_required/mcp with a browser session instead of an API key
404not_foundNo such route (checked before the key), or not yours
404share_not_foundUnknown or ended share link
405method_not_allowedThe endpoint doesn't take that method (see Allow)
409name_takenDesktop name already in use in that region
409plan_sold_outNo server has room for that plan right now
400free_plan_unavailablefree with a plan other than the free one, or an OS with a fee
409too_many_desktopsThe account already has its free desktop
409action_not_allowedNot offered in the current status (see allowedActions)
409desktop_not_runningA command, file, screenshot or stream needs a running desktop
409subscription_activeDeleting a desktop needs its subscription canceled first
409too_many_sharesThe desktop has 20 shares that haven't ended
409desktop_unavailableAn agent can't be set up on that desktop
409agent_existsThe desktop already has an agent of that harness
409too_many_agentsThe account has 20 agents
409too_many_api_keysThe account has 25 API keys
409agent_unreachableThe desktop didn't answer
410share_expiredShare link past its time
403folder_not_readableThe desktop's user can't read the folder to list
403file_not_readableThe desktop's user can't read the file to download
404folder_not_foundNo folder to list at that path
404file_not_foundNo file to download at that path
413file_too_largeAn upload or download over 100 MB
423account_closedThe account is closed
429too_many_attemptsRate limit hit; wait the Retry-After header's seconds
429desktop_busyToo many commands at once on one desktop; wait the Retry-After header's seconds
500internal_errorUnexpected server error
502desktop_unreachableThe desktop didn't answer a command or screenshot
502upload_failedThe desktop didn't take an uploaded file
502payment_provider_errorThe payment provider refused or failed a request
503server_busyA desktop's server had no room for another command in time; see Retry-After