# Scouty API and MCP server: Limits, errors, and policies

## Limits

| Limit | Value |
|---|---|
| Reads | 120 a minute per token |
| Writes | 20 a minute per token |
| Requests per IP address | 120 a minute |
| Setup-code exchanges per IP address | 60 a minute |
| Activations | 25 per campaign per hour |
| Contract uploads | 10 per campaign per hour |
| Campaigns created | 20 per workspace per day |
| Page size | 1 to 100 |
| Response size | About 60,000 characters. Larger pages return fewer items and a `nextCursor` |
| Request body | 64 KB. 4.4 MB for a tool that takes a file |

Over a limit: `429` with `Retry-After` in seconds, or a `refused` result with `retryAfterSeconds`. MCP requests are sent one at a time; a batch is a `400`.

## Errors

```json
{ "error": { "code": "not_found", "message": "No such campaign." } }
```

| Status | Code | Fix |
|---|---|---|
| 400 | `invalid_request` | Check the parameter named in the message. Do not build cursors yourself |
| 400 | `invalid_setup_code` | The setup code was used, expired, or mistyped. Press the tile on the Agents page for a new one |
| 401 | `missing_token`, `invalid_token` | Send `Authorization: Bearer <token>`, or sign in again |
| 401 | `token_revoked`, `token_expired`, `token_orphaned` | Create a new token on the Agents page, or connect the app again |
| 403 | `insufficient_scope` | Create a token with the scope the message names |
| 403 | `wrong_principal` | This token is not allowed to call that tool |
| 404 | `not_found` | The id is not in your workspace. Another workspace's campaign, a missing one, and a malformed id all look the same |
| 409 | `idempotency_conflict` | Use a new key |
| 429 | `rate_limited` | Wait for `Retry-After` |
| 503 | `agent_api_unavailable` | Retry with backoff |

Over MCP, an error is a tool result with `isError: true` and the same code and message.

## Good practice

- One token per agent, with the fewest scopes it needs. An agent that only reads needs no action scope.
- Keep tokens in a secret store. Never in a browser, a mobile app, a prompt, a URL, or a repository.
- Give acting tokens an expiry. Use Never only for read-only tokens you watch.
- Look at **Activity** on the Agents page to see what your agents did.
- Revoke on doubt. It takes one click and works at once.
- Tool results are kept by the AI product you use. That is why creators' contact details never appear in them, and your team's email addresses appear only to a token given `team:manage`. **Activity** names the address when an agent gives someone access, so you can spot one nobody meant. Only your workspace's members can open it, and they can already see your team.

## Versioning

`/v1` only changes by adding: new tools, new optional parameters, new fields. Nothing is renamed or removed inside `/v1`. Tool names are stable. The OpenAPI document is generated from the running server, so it is always current.

## Help

Email founders@scoutnow.me with the error code, the time, and the tool you called. Never send a token.