Errors, pagination and limits

​

Error shape

{
  "error": {
    "type": "conflict",
    "message": "A task is already running on this computer.",
    "active_task_id": "task_mW8mcFPUN7Of"
  }
}

​

Common causes and fixes

​

400 invalid_request

• "prompt" (string) is required: send a non-empty prompt when starting a task.
• Metadata rejected: metadata must be an object with up to 50 keys, keys up to 40 characters, and string values up to 500 characters. Numbers and nested objects aren’t allowed; send "42", not 42.
• Agent id rejected: agent_id is 2 to 40 lowercase letters, numbers and dashes. effort is low, medium, high or null.
• Webhook URL refused: it must be https and resolve to a public address. See Webhooks.
• /respond without an id: send question_id with answer, or approval_id with decision.

​

401 authentication

​

402 payment_required

​

403 permission

​

404 not_found

​

409 conflict

• “No computer is connected to this session.” The session’s status isn’t connected. The customer may have quit the app, closed the laptop or lost the network. Wait for session.connected, or ask them to open GuidingHand.
• “A task is already running on this computer.” One task runs at a time per computer. error.active_task_id is the running task: follow it to the end, or stop it with POST /v1/tasks/{task_id}/stop.
• “An agent with that address already exists.” Pick another agent_id, or PATCH the existing agent.
• “That was already answered by the person at the computer.” (code: "already_answered", answered_by: "customer") The customer answered the question, or decided the approval, on their screen before you did, and theirs is the one the task used. Nothing to fix: carry on following the task. With answered_by: "operator", someone on your team (another process, or the console) answered first. See questions the customer can answer and approvals the customer can decide.
• “That question/approval is not pending.” (code: "not_pending") The id belongs to an earlier question, or the task has ended. Read the task again and respond to the current pending.

​

429 rate_limit

• Too many requests (see rate limits). Wait and retry with backoff.
• Your plan’s limit on tasks running at the same time across the org. Wait for a task to finish, or move to a plan with more.

​

500 server_error

​

Tasks that fail

• the computer disconnected in the middle of a step,
• macOS was dropping the app’s clicks and typing (a permission problem the app reports and offers to fix with a restart),
• the task ran 150 steps without finishing,
• the server was restarted during the task. Start it again.

​

Pagination

{
  "data": [ { "object": "task", "task_id": "task_mW8mcFPUN7Of", "...": "..." } ],
  "has_more": true,
  "next_cursor": "1790434012559"
}

• limit sets the page size, 1 to 100 (default 20).
• When has_more is true, pass next_cursor as cursor to get the next, older page. When it is false, next_cursor is null.
• Keep the same filters (session_id, agent_id, status) on every page.

let cursor = null;
do {
  const qs = new URLSearchParams({ status: 'failed', limit: '100', ...(cursor ? { cursor } : {}) });
  const page = await gh('GET', `/v1/tasks?${qs}`);
  for (const t of page.data) console.log(t.task_id, t.error);
  cursor = page.has_more ? page.next_cursor : null;
} while (cursor);

cursor = None
while True:
    params = {"status": "failed", "limit": 100}
    if cursor:
        params["cursor"] = cursor
    page = gh("GET", "/v1/tasks", params=params)
    for t in page["data"]:
        print(t["task_id"], t["error"])
    if not page["has_more"]:
        break
    cursor = page["next_cursor"]

​

Rate limits