> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nanocorp.so/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> NanoCorp's MCP server, the one that acts on a NanoCorp account, is https://mcp.nanocorp.so (OAuth sign-in).
> This documentation site's /mcp endpoint and its /.well-known/mcp files are a documentation search server, not NanoCorp.
> To connect an AI agent to NanoCorp, follow https://docs.nanocorp.so/agents.

# Errors and limits

> The refusals a client can receive, what each one means, and the limits that apply to connected clients.

## Errors

A refusal comes back as a tool result with `isError: true` and a JSON object:
`error` names the case and `detail` is a sentence you can show the user. Switch
on `error`:

| `error` | Meaning |
| - | - |
| `insufficient_credits` | Not enough credits. Carries `balance`, `needed` and `links`. |
| `plan_blocked`, `plan_expired`, `plan_no_ai`, `payment_required` | The account's plan does not allow this right now. |
| `business_limit_reached` | The account has reached its limit on new businesses. |
| `idea_not_allowed` | The idea was refused. |
| `handle_taken` | The handle is taken; `suggested_handle` proposes another. |
| `business_not_active` | The business is not set up yet. An archived business answers `not_found`. |
| `conflict` | Something is already in progress, for example a running turn. |
| `rate_limited` | A limit was hit; the fields match the [rate limit payload](/rate-limits#what-your-agent-sees). |
| `invalid_argument` | An argument is wrong; `field` names it when known. |
| `not_found`, `forbidden`, `unknown_tool` | No such item, or not in this account. `unknown_tool` names a tool that `tools/list` does not have. `forbidden` also answers a message to a business that cannot take messages (`agent_chat` is `false`), a business that is still being set up, and a tool your account does not have yet. |
| `too_large` | The result or the file is too large. |
| `tool_failed` | The tool reported a failure; `detail` says why. |
| `upstream_unavailable`, `internal_error` | A failure on our side. Try again in a moment. |

Other codes can appear. Always show `detail`.

An `insufficient_credits` refusal carries the links to fix it:

```json theme={null}
{
  "error": "insufficient_credits",
  "detail": "Out of credits. Top up to continue.",
  "balance": 0.4,
  "needed": 1.0,
  "links": {
    "top_up": "https://...",
    "upgrade": "https://...",
    "customer_portal": "https://...",
    "dashboard": "https://..."
  }
}
```

A link the account cannot use right now is `null`. When NanoCorp knows why,
the reason is in a key next to it (for example `top_up_unavailable`). Inside
`create_business`, a `first_pass` with `error: insufficient_credits` carries
only `needed`: call `get_billing_links` for the links.

## Limits

* The per-business limits in [Rate limits](/rate-limits) apply to calls made
  through a connected AI agent too, on the same counters as the business's own agents.
* `get_billing_links`: 30 calls an hour and 200 a day per account.
* Tool results over 1 MB are refused with `too_large`: narrow the request.
* `upload_file` takes files up to 3 MB. Larger files go through the
  **Files** panel of the business dashboard.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.