Why is my AI agent's computer not responding? Orgo API errors explained

TL;DR

When an agent's computer stops answering on Orgo, the status code plus the code field tell you which case you are in:

• 401 or 403: a key or workspace problem. Fix the key or its scope. Retrying will not help.
• 402: a billing problem. The computer needs credit or a plan that funds running computers.
• 409: the computer is in the wrong state for the call (asleep, waking, still saving, being moved, or stopped). The code says which, and whether to wait or to call resume or start.
• 429: a plan rate limit. Wait retry_after seconds.
• 503: read the body before you retry. resuming and Service temporarily unavailable. are transient. Could not reach the desktop on a suspended computer that is Paused or hourly is not: Orgo never wakes those automatically, so retrying never helps. Call POST /computers/{id}/resume.
• 504 with code: "timeout": the command outlived the time the API allows.

If a computer reads 200 on GET /computers/{id} but its actions keep failing, call GET /computers/{id}/health, then POST /computers/{id}/heal. Do not delete it. Deleting drops the disk.

What does an Orgo API error look like?

An Orgo API error is a JSON response with an error string, and usually a machine-readable code and a request_id. Every /api response also carries an X-Request-Id header, on errors and successes alike, so you can log an id even when the body has none or is not JSON:

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

When the failure came from the desktop itself rather than Orgo's control plane, the response adds upstream_status. No upstream_status means the error happened in the control plane (auth, lookup, validation). An upstream_status of 400 means the desktop rejected the request body, and 500 means the desktop could not carry out the action (Troubleshooting).

When an answer says when to ask again, it carries a Retry-After header, in seconds. Most also repeat it as retry_after in the body.

The OpenAI-compatible /v1/chat/completions endpoint is the one exception: its error is an object with type, message, and code.

Keep the request_id. It maps to a server-side log line and is the first thing support asks for.

When does an Orgo computer wake up on its own?

Check this rule first when something that worked yesterday fails.

An action (a command, a click, a keypress, a new screen) on a suspended computer resumes it first, then runs. You do not need to call resume. The exceptions, where the action does not wake it:

A read (a GET, such as a screenshot) wakes an ordinary suspended computer too, with the same exceptions. Two cases stay asleep: a computer that was moved to storage, and a Bops computer that went to sleep for being idle. There a read answers 409 computer_asleep. An action wakes them, unless the table above says otherwise.

So for an agent: a 503 from a computer that you or a teammate paused is not a network blip. Resume it.

Which Orgo errors are safe to retry?

The 404 above is what an API key gets. A signed-in browser session gets 404 Desktop not found instead, and /bash adds a hint. Plan rate limits, and the RateLimit-* headers that come with them, are listed in Account limits.

Why does my agent get a 409 when the computer is not running?

Because the computer is no longer running. A computer's status is one of creating, running, restarting, updating, suspending, suspended, resuming, frozen, stopped, error, or deleted (llms.txt). A call on an ordinary suspended computer resumes it, as described above. A call on a computer Orgo will not wake automatically fails instead, and the tables above say what each answer means.

Pick the wake-up call by status:

A resume that returns 202 with status: "resuming" is still bringing memory back. Poll Get suspension until status reads running, then send the action again. A start waits for the boot. If the boot takes longer than five minutes, or you ask for async, start returns 202 with an operation and a poll_url to poll instead.

# Wake a paused computer, then retry the action
curl -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/resume \
  -H "Authorization: Bearer $ORGO_API_KEY"

Calling /resume on a frozen computer returns 409 with Computer is not suspended (status: frozen). Use /start for that one. A stop freezes the computer, so a computer you stopped reads frozen. For what each lifecycle call keeps, see How do you pause, fork, or clone an AI agent's computer?

Why did my bash command time out?

There are two different timeouts, and they look different.

The command's own timeout. Execute bash takes a timeout in seconds. Leaving it out allows 200 seconds. Sending it clamps it to 1 to 300, so a larger value silently becomes 300, and 0 or a non-numeric value becomes 10. On Linux, a command killed by this timeout returns exit_code: -1. On Windows, where the endpoint runs PowerShell, it returns 200 with exit_code: 124, error: "timeout", and the output captured so far.

The API hop's limit. Orgo waits the command's timeout plus 30 seconds for the desktop to answer. If the call outlives that, you get 504 with code: "timeout", the message The command exceeded the allowed time and was aborted., and no output. Because of the 30-second margin, the command's own timeout normally fires first.

Two more things that trip agents up:

• A command that exits non-zero is not an error status. The call returns 200 with success: true, and exit_code tells you whether the command worked. Check exit_code, not the HTTP status.
• On a computer with several screens, ?screen= naming a screen that does not exist returns 404 and nothing runs.

For long jobs, start the work in the background inside the computer and poll for a result file or process, instead of holding one call open.

How do you recover a stuck AI agent computer?

A computer is stuck when GET /computers/{id} returns 200 but action calls fail.

1. Check health. GET /computers/{id}/health is read-only: it never wakes, resumes, or restarts anything. It returns overall (healthy, degraded, or stopped) and a checks list covering the status, the in-computer agent, the exec path, the display, and VNC. A computer that is not running reads stopped, with the live checks skipped.
2. Heal. POST /computers/{id}/heal with no body tries automatic recovery, then checks again. It respects a Pause and never restarts. If the computer is still not healthy, the answer's recommendation says what to do next: resume a paused computer, wait for one moving to or from storage, or restart.
3. Restart. Call /heal again with {"action": "restart"}, or POST /computers/{id}/restart. Files on disk survive a restart; running processes do not. The /heal restart waits up to about 45 seconds for the exec path to answer before it replies.
4. Escalate. If restart fails too, collect the request_id from a few attempts and contact support. Do not delete the computer. Deleting drops the disk.

# Read-only health check
curl https://www.orgo.ai/api/computers/$COMPUTER_ID/health \
  -H "Authorization: Bearer $ORGO_API_KEY"
 
# Safe automatic recovery (never restarts)
curl -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/heal \
  -H "Authorization: Bearer $ORGO_API_KEY"

Restart is not the answer for every status (Restart computer):

• A frozen computer has no host, so restart returns 409 with code: "stopped" and This computer is stopped. Use Start to turn it back on. Use /start.
• A suspended computer returns 409 with code: "suspended". Resume it first.
• A computer being moved returns 409 with code: "migrating". Wait a few minutes.
• A dedicated GPU computer whose restart recreates the machine needs {"clear_disk": true}, because that restart deletes everything outside /workspace. Without it you get 409 with RESTART_CLEARS_DISK. With it, restart answers 202 with an operation and a poll_url. /heal will not restart one of these for you.

Every other computer's restart answers 200 after the reboot finishes, not when it is queued.

What do the 503 diagnostic fields tell you?

When Execute bash or Execute Python returns 503 Could not reach the desktop, the body also carries vm_status, host_reachable, desktop_api_reachable, and a hint. Other actions (click, type, screenshot) return the plain 503 without them, so use /health there.

The hint says the same thing in a sentence. The body also has a desired_status field. It is always null, so do not branch on it.

How should an agent loop handle Orgo errors?

import time, requests
 
RETRY_CODES = {"computer_waking", "suspend_in_progress", "migrating", "resuming", "rate_limited"}
WAKE_CODES = {"computer_asleep", "resume_required", "paused"}
 
def act(session, base, computer_id, path, body, attempts=4):
    url = f"{base}/computers/{computer_id}/{path}"
    for i in range(attempts):
        r = session.post(url, json=body)
        if r.ok:
            return r.json()
        try:
            data = r.json()
        except ValueError:
            data = {}
        code = data.get("code")
        rid = data.get("request_id") or r.headers.get("X-Request-Id")
        if code in WAKE_CODES or data.get("vm_status") == "suspended":
            session.post(f"{base}/computers/{computer_id}/resume")
        elif code not in RETRY_CODES and r.status_code != 503:
            raise RuntimeError(f"{r.status_code} {code} {data.get('error')} request_id={rid}")
        time.sleep(int(r.headers.get("Retry-After", 2 ** i)))
    raise RuntimeError(f"gave up, last request_id={rid}")

The loop resumes a computer that will not wake by itself, retries only the transient cases, honors Retry-After, and surfaces request_id on every failure so a person can trace it. If a plain 503 keeps coming back, call /heal rather than looping forever.

Driving Orgo through MCP instead of raw HTTP? See Orgo MCP for AI agents.

What should you send support?

Three things:

• The request_id from the error response, or the X-Request-Id header. This is the most important field.
• The exact request: method, URL, and body, with secrets removed.
• The full error response.

Email contact@orgo.ai, or ask in the Orgo Discord linked from the Troubleshooting guide.

FAQ

What does "Could not reach the desktop" mean on Orgo? The control plane could not connect to the computer. If the computer is suspended and Paused or hourly, Orgo did not wake it, so call /resume. Otherwise it is usually transient: retry with backoff of 1s, 2s, 4s, then call /heal.

Does an API call wake a suspended Orgo computer? An action does (a command, a click, a keypress), unless the computer was Paused, is hourly, is being moved, or the owner's plan cannot fund it. A read such as a screenshot wakes it on the same terms, except a computer in storage or a Bops computer asleep for being idle: those answer 409 computer_asleep.

Why do I get 401 Invalid API key when the key looks right? The token is not a known Orgo key. Check for stray whitespace or a truncated copy, and make a new key if needed. If the answer is 503 Service temporarily unavailable. instead, the fault is on Orgo's side; retry and do not rotate the key.

What is workspace_scope_mismatch? A 403: a workspace-scoped key was used on a different workspace, or on an endpoint that needs an account-wide key. Use an account-wide key or a key scoped to that workspace (Authentication).

Why does my computer say resume_required? It runs on hourly credit and is asleep in storage, so an action does not wake it. Call /start or /resume to reserve its running time, then retry.

Why does restart return 409 stopped? The computer is frozen (stopped), so it has no host to reboot. Call /start.

Does restarting an Orgo computer delete my files? No, files on disk are kept and running processes are not. The exception is a dedicated GPU computer whose restart recreates the machine: it clears everything outside /workspace and asks you to confirm with clear_disk.

Why does my bash call return 200 when the command failed? success: true means the command ran. Whether it worked is in exit_code (Execute bash).

What is the maximum bash timeout? 300 seconds. Larger values are clamped to 300, and the default is 200.

Should I delete a computer that will not respond? No. Call /heal, then restart, then contact support with request_ids. Deleting a computer drops its disk.

Related

• How do you pause, fork, or clone an AI agent's computer?
• The Orgo computer use API
• Orgo MCP for AI agents
• Scale AI agent computers to thousands

Sources

• Troubleshooting
• Execute bash
• Execute Python
• Resume computer
• Start computer
• Restart computer
• Get suspension
• Authentication
• Account limits: plan rate limits