Errors, retries and recovery
Interpret errors, reconcile uncertain requests and recover without duplicate work.
Recover the existing request before submitting another mutation. Use the error code, request ID, current revision and saved operation key to decide whether to sign in, reconcile or continue.
On this page
Overview
A timeout does not establish that nothing happened. For a CLI mutation, the pending request journal saves the target, payload, query and key before sending:
artie request resume original-request-key --json
artie task watch TASK_UUID --wait 120 --jsonRecover the same operation. Generic resume refuses person decisions; a person must use the current interactive proposal. Do not switch keys to replay a possibly successful operation. For external effects, reconcile the exact target and provider receipt before retrying.
A lost rotating refresh response is retained as uncertain in the credential store and is not automatically repeated. Sign in again using the supported login flow to recover; an active login/refresh owner must finish before another process takes over. Serialize login/logout per profile.
| Condition | What to do |
|---|---|
setup_required with setup URL | Complete the returned workspace binding normally; don't start business commands yet. |
401 authentication | Recover the intended environment/client sign-in. A different environment's token will not work. |
403 denial or hidden/not-found response | Check your permitted target/association. Do not search other users' private objects to work around it. |
404 missing object | Read the returned customer explanation. Missing and restricted records may deliberately avoid exposing existence. |
409 conflict | Read current revision/state and reconcile the intended operation. |
429 throttling | Honor Retry-After for a safe eligible request; reconcile uncertain writes first. |
| Provider/transport unavailable | Preserve the original request and effect evidence; recover the named condition. |
| Unreadable extraction | Keep the original file, identify the failed read/parse stage, and use supported recovery rather than reuploading by default. |
Error codes are read from the canonical error.code. Some hosts wrap them in a generic outer tool error such as INVALID_ARGUMENT; that outer label is not sufficient to diagnose a canonical permission, conflict or provider failure. Preserve both layers and the request ID without private payloads.
CLI exit codes:
| Exit | Meaning |
|---|---|
| 0 | Command or deterministic check succeeded |
| 2 | Invalid arguments |
| 3 | Authentication or setup needed |
| 4 | Forbidden or hidden/not found |
| 5 | Revision/idempotency conflict |
| 6 | Waiting or interrupted observation |
| 7 | Provider, transport or execution failure, or unknown outcome |
--json puts structured output on stdout and structured errors on stderr. Login instructions and human prompts are separate. doctor reports environment, known source revision and authenticated identity; it does not certify provider health, deployment of every frontend/worker, or success of a task.
Delegated requests use shared minute-window limits: essential reads/controls use a workspace bucket up to 600 and a per-grant bucket up to 240; writes use up to 120 and 60 respectively. Other readers/bootstrap services may apply additional limits. These are maximum limits; follow the server’s actual throttle response and avoid unbounded parallel requests.
HTTP errors and CLI exit codes
| HTTP | Meaning | Recovery |
|---|---|---|
| 400 | Invalid request | Repair the arguments before execution. |
| 401 | Invalid or expired authentication | Restore the intended environment login. |
| 403/404 | Denied, missing or concealed record | Check authority or follow the actual setup link. |
| 409 | Revision, version or key conflict | Read current state and reconcile the same operation. |
| 429 | Rate limited | Honor Retry-After; reconcile uncertain writes first. |
| 500 | Internal/configuration failure | Keep the request ID and contact support without credentials. |
| 503 | Read not ready | Use bounded safe-read observation. |
CLI exit codes: 0 command success; 2 invalid arguments; 3 auth/setup; 4 denied or hidden/not-found; 5 conflict; 6 waiting or interrupted observation; 7 execution/transport failure or unknown response. Success data is written to stdout; structured errors to stderr. A watch exit 0 can mean needs_you, so inspect the returned task state.
Need help with your workspace?
Contact support