Error codes

API error responses, with hints for what to do next.

The orchestrator returns errors as JSON:

{
  "code": "<machine-readable>",
  "message": "<human-readable>"
}

The CLI surfaces both, and adds a one-line hint when applicable.

Authentication

Code	HTTP	What it means	Action
`unauthorized`	401	Missing / invalid bearer token	Re-run `artifacts login`; check the JWT hasn't expired.
`forbidden`	403	Token valid but lacks permission	The user (or service token) doesn't own the workspace. Check `artifacts workspace list`.

Code	HTTP	What it means	Action
`workspace_not_found`	404	Identifier doesn't match an existing workspace	Confirm the workspace name is right; `artifacts workspace list` shows what you own. The CLI accepts the short form `<name>` (resolves to your own handle), `<handle>/<name>`, or the full `artifacts://<handle>/<name>`.
`workspace_exists`	409	A workspace with that name already exists for this user	Pick a different name, or `artifacts workspace delete <name>` first. The 409 body includes an `existing` field with the live state, which `artifacts workspace create` uses to resume `pending_format` automatically.
`workspace_not_active`	409	Tried to mount or `format-completed` against a workspace that's not `active`	If `pending_format`, re-run `artifacts workspace create <name>` to resume. If `deleting` / `deleted`, recreate.
`workspace_not_completable`	409	`/format-completed` called on something other than `pending_format`	Almost always means the workspace is already `active`, in which case the orchestrator returns 200 idempotently via the active short-circuit. If you're seeing this 409, it's likely a stale CLI binary; reinstall.
`invalid_request`	422	`/format-completed` called with no `setting` key under the workspace prefix in the metadata service	Phase 2 didn't actually run, or it ran against a different bucket. The `message` tells you to re-run `juicefs format`; in practice re-run `artifacts workspace create`.

Code	HTTP	What it means	Action
`tenant_exists`	409	A tenant with that slug already exists for this user	Reuse the existing tenant slug in subsequent calls, pick a different slug, or delete the tenant before recreating it.

Code	HTTP	What it means	Action
`metadata_acl_provisioning_failed`	500	The orchestrator couldn't reach the metadata service to set up your mount-session permissions	Transient. Retry in a few seconds. If it persists past 60 s, contact us; there's an alert on our side too.

Code	HTTP	What it means	Action
`invalid_request`	422	Request body / params don't satisfy the schema	The `message` field has the specific complaint, e.g. `storage.bucket is required` or `ttl_seconds must be between 60 and ...`.

Code	HTTP	What it means	Action
`internal_error`	500	Unexpected server-side failure	Retry once. If it repeats, contact us with the timestamp + your workspace identifier.

These never have an HTTP code; the CLI surfaces them before the request hits the orchestrator.

Symptom	Hint
`path /mnt/work is already a mount point`	`artifacts unmount /mnt/work` first. The CLI reads `/proc/self/mountinfo` to detect this.
`BYO mode requires ARTIFACTS_S3_ACCESS_KEY_ID and ARTIFACTS_S3_SECRET_ACCESS_KEY`	Export them in your shell or run `artifacts storage set --access-key-id ... --secret-access-key ...`.
`byo_env requires ARTIFACTS_S3_ACCESS_KEY_ID and ARTIFACTS_S3_SECRET_ACCESS_KEY (set them in the environment or run \`artifacts storage set`)`	Same as above; the cache is also empty.

These come straight from the storage backend; the message includes the underlying S3 error code.

For BYO workspaces:

What you'll see	Likely cause
`Object storage test failed: ... AccessDenied`	Bucket policy doesn't grant your AK list/get/put.
`Object storage test failed: ... NoSuchBucket`	Bucket name typo or wrong endpoint.
`Object storage test failed: ... InvalidAccessKeyId`	AK/SK pair is wrong or expired.
`Object storage test failed: ... SignatureDoesNotMatch`	Region mismatch (Tigris uses `auto`; AWS regions are `us-west-1` etc.).

Reproduce locally with aws s3 ls s3://<bucket>/ --endpoint-url <endpoint> to confirm before re-running workspace create.

For managed workspaces:

What you'll see	Likely cause
`Object storage test failed: ... InvalidAccessKeyId` on a fresh `workspace create`	AWS IAM eventual consistency. The orchestrator just minted credentials and they haven't propagated globally yet (~5–10s). Re-run `artifacts workspace create <name>` after a short wait, it resumes the pending_format workspace and reuses the same creds, which by then are valid.
`internal_error` with `managed_provisioning_failed: ...`	The orchestrator couldn't talk to AWS IAM (transient AWS issue, or an orchestrator-side IAM permissions regression). Retry; if it persists, contact ops.
`internal_error` with `managed_storage is malformed; delete + recreate`	The workspace's `managed_storage` jsonb is missing required fields (rw / ro / prefix). Should never happen organically; usually means a hand-edit or a partial migration. `artifacts workspace delete --yes <name>` (cron will retry the IAM teardown) and recreate.