> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orgo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Map common API errors to the action that fixes them.

Orgo API error responses are JSON with an `error` string. The OpenAI-compatible `/v1/chat/completions` endpoint is the exception: its `error` is an object with `type`, `message`, and `code`. When a computer action fails at the desktop, or while Orgo is reaching it, the response also carries a `request_id` to use when contacting support, and some carry a machine-readable `code`.

```json theme={null}
{
  "error": "Could not reach the desktop. Try again in a moment.",
  "request_id": "f0c2c4a8-9d8e-4d2f-b8a6-2a9a4c2d4b1f",
  "code": "ECONNREFUSED"
}
```

When the error originated on the desktop side of the request, the response also includes the upstream status:

```json theme={null}
{
  "error": "this VM already has 4 screens, which is the limit",
  "request_id": "f0c2c4a8-9d8e-4d2f-b8a6-2a9a4c2d4b1f",
  "upstream_status": 409
}
```

Always include `request_id` when emailing [spencer@orgo.ai](mailto:spencer@orgo.ai) about a failed call. It maps directly to a server-side log line.

## Authentication

| Symptom | What it means | Fix |
| - | - | - |
| `401 Invalid API key` | The Bearer token in your `Authorization` header is not a known Orgo API key. | Generate a new key at [orgo.ai/settings/credentials](https://www.orgo.ai/settings/credentials). Check for stray whitespace. |
| `401 Authentication required` | No `Authorization` header on the request (or a token without the `sk_` prefix), and no signed-in browser session. | Set `Authorization: Bearer $ORGO_API_KEY`. |
| `Service temporarily unavailable.` with `401` or `503`, depending on the endpoint | Orgo could not verify credentials because of a server-side fault. Your key is not the problem. | Retry after a short wait. Do not rotate your key. |
| `You do not have access to this workspace.` with `403` or `401`, depending on the endpoint | The computer or workspace is not in a workspace you belong to, or you were removed from the workspace. | Confirm the workspace ID, or ask the workspace owner to re-invite you. |
| `workspace_scope_mismatch` in the `error` message, with `403` or `401`, depending on the endpoint | The API key is workspace-scoped and the request targets a different workspace, or an endpoint that needs an account-wide key. | Use an account-wide key, or create a key scoped to the target workspace. See [Authentication](/api-reference/authentication). |

Orgo API keys come in two flavors: **account-wide** (can access every workspace your account can) and **workspace-scoped** (locked to one workspace and refused everywhere else). Pick the scope when you create the key at [orgo.ai/settings/credentials](https://www.orgo.ai/settings/credentials).

## Computer not responding

| Symptom | What it means | Fix |
| - | - | - |
| `404 Desktop not found` | The ID in the URL doesn't match a computer your account can see. | Re-fetch the ID from `GET /workspaces/{id}`. |
| `402 Choose a plan to continue.` | The computer is a trial computer whose trial has ended. | Choose a paid plan in the dashboard. |
| `400 Desktop instance not available` | The computer record exists, but it never got a backing VM (still booting or failed). | Wait a few seconds and retry. If it persists, `POST /computers/{id}/restart`. |
| `503 Could not reach the desktop. Try again in a moment.` | The control plane could not connect to the desktop. Usually transient. | Retry with exponential backoff (1s, 2s, 4s). If it keeps failing, restart the computer. |
| `409 Conflict` | The action is blocked by the computer's current state, for example `Computer must be running to resize`. | Read the message; restart or stop the computer if needed. |

## Action errors (bash, click, type, exec, etc.)

When an action endpoint returns a non-200, the `upstream_status` field tells you whether the failure came from Orgo's control plane or from the desktop itself.

| `upstream_status` | Meaning |
| - | - |
| Not present | The error originated in Orgo's control plane (auth, lookup, validation). |
| `400` | The desktop rejected the request body, for example a click with `repeat` above 10. |
| Not present, `code: "timeout"`, status `504` | The command ran past its allowed time. Common with long bash commands; pass a higher `timeout` in the body (bash defaults to 200 seconds and caps it at 300). |
| `500` | The desktop could not carry out the action. If it persists, capture the `request_id` and contact support. |

## Recovering a stuck computer

A computer is "stuck" if it returns `200` on `GET /computers/{id}` but action calls fail.

1. `GET https://www.orgo.ai/api/desktops/{instance_id}/proxy/health`. If this returns 200, the desktop is up and the issue is in the control plane. Retry your action.
2. If `/health` fails, `POST /computers/{id}/restart`. Files on disk are preserved across a restart; running processes are not.
3. If restart fails, capture `request_id`s from a few attempts and email [spencer@orgo.ai](mailto:spencer@orgo.ai). Do not delete the computer; deletion drops the disk.

## Reporting a bug

When something is broken, send:

* The `request_id` from the error response (the most important field).
* The exact request you made (method, URL, body, redacted of secrets).
* The full error response.

Email: [spencer@orgo.ai](mailto:spencer@orgo.ai). Discord: [discord.gg/tbYGpvnnJD](https://discord.gg/tbYGpvnnJD).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.