Errors

The API, the MCP tools and stow --json all return errors in one shape: { "code", "error", "retryable", "docs" }. Branch on code, show error to the user, and retry only when retryable is true. docs links to the entry below.

Every /api and /mcp response carries RateLimit-Policy: "default";q=120;w=60: 120 requests a minute per key, or per address without one.

bad_request

HTTP 400 · retryable: no

The request can't work as sent: a missing or malformed field, a bad cursor, a URL that isn't a Stow file.

Read the message, fix the input, and send it again. Don't retry it unchanged.

unauthorized

HTTP 401 · retryable: no

No credential, or one Stow doesn't accept: a wrong, revoked or expired API key, an expired upload link, or an OAuth token for another server.

Ask the user for a new API key from stow.sh/account, or sign in to the connector again. Never print the key.

forbidden

HTTP 403 · retryable: no

An upload-only API key tried to list or delete files.

Upload-only keys can only add files. Ask the user for a full-access key if listing or deleting is needed.

payment_required

HTTP 402 · retryable: no

The account has no active plan, so it can't upload.

Tell the user to subscribe at stow.sh/account (from $5 a month). Don't retry.

not_found

HTTP 404 · retryable: no

No such file, or it belongs to someone else, or an unknown API route.

Check the URL or key. Someone else's file looks the same as a missing one, on purpose.

method_not_allowed

HTTP 405 · retryable: no

The path exists but not with this HTTP method.

Use the method in the message, for example PUT to upload and DELETE to delete.

too_large

HTTP 413 · retryable: no

The file is over 100 MB, or over 20 MB sent inline to the put_file tool.

For inline uploads, use create_upload_url. Over 100 MB, compress or trim the file, or link the source instead.

storage_full

HTTP 413 · retryable: no

The upload would take the account past its plan: 10 GB on Personal, 100 GB on Studio.

Tell the user. They can delete files, or move from Personal to Studio at stow.sh/account.

rate_limited

HTTP 429 · retryable: yes

More than 120 requests in a minute from one key or address.

Wait the seconds in the Retry-After header, then retry. The CLI exits 5.

confirmation_required

HTTP 400 · retryable: no

delete_file was called without confirm: true.

Check the user wants the file gone, then call again with confirm: true.

fetch_failed

HTTP 502 · retryable: yes

put_from_url couldn't download the source: it answered with an error or didn't answer.

Check the URL is public. Retry once; if it fails again, tell the user.

unavailable

HTTP 503 · retryable: yes

A part of Stow isn't switched on or is briefly down.

Retry after a short wait.

failed

HTTP 500 · retryable: yes

Stow hit an unexpected error.

Retry once. If it keeps happening, email hello@stow.sh with the time and the request.