# 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"?: ... }`.

## 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 |
| `files:write` | Patch tags/description, mkdir |
| `files:delete` | Soft-delete files |
| `files:upload` | Presign upload + complete |
| `files:download` | Presign download |
| `intelligence:read` | Get intelligence config/progress |
| `intelligence:write` | Patch config, backfill |
| `agent:run` | Bucket agent |
| `shares:read` / `shares:write` | Shares |
| `transfers:read` / `transfers:write` | Transfers |

MCP tools enforce the same scopes — see [MCP tools](/docs/mcp/tools).