Errors and limits

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.
`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:

{
  "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 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.

AI agents

MCP reference

Errors and limits

Errors

Limits

​Errors

​Limits

Errors

Limits