A credential is rejected
For HTTP 401, check expiry, the API origin, and the selected credential file.BEAD_API_KEY overrides a saved file. Private credential files must have mode 0600.
For a permission refusal, use a credential with the required scope. Ownership and billing administration require admin authority. See Agent authentication.
A machine cannot start
For HTTP 429, read the named limit,maximum, usage, reset_at, and next_action. Honor Retry-After when present. Resource limits may require releasing capacity rather than waiting for a timer.
free_capacity_full means trial capacity cannot admit the request. Follow its retry guidance or add credit for paid admission. See Limits and availability.
For HTTP 402 insufficient_credit, inspect reservations and funded deadlines. Adding credit alone does not extend a temporary machine’s timeout. See Credit and payment problems.
A machine does not answer
Inspect readiness before sending commands.machine_unavailable is retryable and carries retry guidance. machine_lost is terminal and marks the response retryable: false; repeatedly reconnecting cannot restore that machine.
Check Service status, then Connection problems for forwarding or desktop-specific failures.
A command failed
Read the command’s exit code, stdout, and stderr. A command can fail even when HTTP transport succeeds. Connect terminal errors can arrive with HTTP 200, so inspect the protocol result as well. CLI guest errors preserve bounded status and response evidence.truncated means part of the response was omitted; incomplete means the response could not be fully read.
The reply was lost
Do not blindly repeat a command that may have run. Recover output using its execution or result identifier. For worktrees, usebead worktree status --execution ID; see Worktree problems.
An idempotency mismatch means the request changed under the same key. Keep the original request and inspect its outcome before starting different work. See Command output and recovery.