My agent gets an error from teem
What 401, 402, 403, 404, 422 and 429 mean from teem's API and MCP server, and the fix for each.
REST and MCP return the same errors. Over REST they come as HTTP status codes. Over MCP, the tool result is marked isError: true and carries the same body:
{ "error": { "code": "forbidden", "message": "You do not have permission for this action.", "details": {} } }
| Status | Code | What it means | Fix |
|---|---|---|---|
| 401 | unauthorized |
The access key is missing, mistyped or revoked | Create an agent in Settings → API & MCP and use its key |
| 402 | subscription_required |
The organization's trial or subscription ended | An owner subscribes at details.billing_url. Retrying won't help |
| 403 | forbidden |
The person behind the key can't do this | Owner-only actions need a key an owner created |
| 404 | not_found |
Nothing with that id in this key's organization | Check the id, and that the key belongs to the right organization |
| 422 | validation_failed |
A value is wrong | details names the field |
| 429 | rate_limited |
More than 120 requests in a minute | Wait for Retry-After, which is 60 seconds |
Start with whoami
whoami over MCP, or GET /api/v1/me over REST, tells you which person, organization and role a key belongs to. It works even while the organization is read-only, so it's the first call to make when something looks wrong.
One key, one organization
A key works in exactly one organization, as the person who created it, with that person's current role. There's no organization parameter. To work in two organizations, create an agent in each one.
What agents can't do
A few actions need a person signed in to the dashboard, on purpose: creating or revoking agents, inviting or removing people, rotating the signing secret, connecting Slack, and billing. An agent that needs one of these should ask you to do it.
The API reference and MCP reference list every endpoint and tool.