Menu
Status codes, errors, and scope matrix·View as Markdown
Errors & scopes
Status codes
| Code | Meaning |
|---|---|
| 400 | Bad request (missing fields, invalid estimate token, protocol unsupported) |
| 401 | Missing / invalid Bearer token |
| 403 | Insufficient scope, workspace mismatch, bucket not allowed, feature disabled |
| 404 | Not found — or dogfood gate (intentionally opaque) |
| 502 | Upstream job kick failed (e.g. Trigger drain) |
Error body is usually JSON: { "error": "...", "required"?: ... }.
Cloudflare 1010 is not an app status code. Bot Fight Mode blocked the HTTP client before file.rocks. Agents must use MCP complete_upload, not REST upload-complete.
Scope matrix
| Scope | Used for |
|---|---|
workspaces:read | List/get workspaces |
buckets:read | List/get buckets |
buckets:write | Create/patch buckets |
buckets:delete | Delete buckets |
files:read | List, get, search, similar (index only — not a live bucket listing) |
files:write | Patch tags/description, mkdir, move. Does not register uploads |
files:delete | Soft-delete files |
files:upload | presign_upload + complete_upload (or REST presign + upload-complete). Upload + read is enough |
files:download | presign_view (inline) and presign_download (attachment). preview 1h / embed 7d. Durable view URL only when publicDomain / file.url |
intelligence:read | Get intelligence config/progress |
intelligence:write | Patch config, backfill |
agent:run | Bucket agent |
automations:read / automations:write | Automations & Trash settings |
suggestions:read / suggestions:write | Cleanup suggestions |
shares:read / shares:write | Shares |
transfers:read / transfers:write | Transfers |
MCP tools enforce the same scopes — see MCP tools. Upload steps: Upload flow.