# Errors

Authentication and access errors generally return:

```json
{
  "error": "workspace_forbidden",
  "error_description": "Token does not have access to this workspace",
  "request_id": "REQUEST_ID"
}
```

HTTP 401 means invalid credentials; 403 means missing permission or a disallowed
origin; 404 means a missing resource. Validation commonly uses 422.
A 403 with `two_factor_required` means the workspace's owner requires
[two-step verification](https://vatio.ai/docs/team#two-step-verification-and-sessions) and the
account does not have it yet.
Deploy and chat errors may use `error_key` and `error_message`.
A missing record, a record that fails validation, and the knowledge endpoints
use `{ "error": { "code": "...", "message": "..." } }`.
Retain `request_id` when the response includes one.

When the platform knows the next step, the error also carries `hint`: one
sentence saying what to run or change, such as
`"Run \`vatio login\`, then retry the same command."`. The CLI prints it as
`Next:`. Treat it as the recovery step rather than retrying the same request.