Errors and limits

Error format

Every error is JSON with an error field. It is either a short machine-readable code or a human-readable sentence:

{ "error": "Server not found" }

Coded errors add a message you can show to a person, and limit errors add links:

{
  "error": "source_limit",
  "message": "Free tier includes 2 sources per server. After that, each additional source is $3.",
  "limit": 2,
  "purchaseUrl": "https://buy.stripe.com/...",
  "upgradeUrl": "https://appatools.com/mcp-studio/account/billing"
}

Branch on error, and show message. Each reference page lists the exact codes an operation returns.

Status codes

Status	Meaning	What to do
400	The request is missing something or is invalid	Fix the request. error says what
401	No API key, or the key is invalid or revoked	Check the Authorization header
402	A plan limit on sources was reached	Send purchaseUrl or upgradeUrl to whoever pays
403	The key is not allowed to do this, or the account is at its server limit	See error: key_scoped, enterprise_limit, request_log_locked
404	No such server, source, tool, or rule on this account, or outside this key's scope	Check the ID or slug
405	The request method is not served at this URL	See the operation's reference
409	Conflicts with the current state, such as a duplicate source or a full tool limit	See error
422	Understood but refused, such as an inaccessible private repository or a rejected credential	See error and message
429	Rate limited	Wait Retry-After seconds
503	A feature is temporarily unavailable	Retry later

Plan limits

These are the free plan's limits. Paid plans raise them; see Billing.

Limit	Free	Error when exceeded
Servers per account	3	403 enterprise_limit on create
Sources per server	2, or 5 on your first server during the trial	402 source_limit on create, 402 source_limit_reached when adding
Tools per server	3 to 10	400
Custom tools per account	5	409 custom_tool_limit
Retrieval rules per server	10	409
MCP requests per month	50, shared across all of your servers	A JSON-RPC error on the MCP endpoint

Check headroom before acting with GET /api/billing/usage.

Rate limits

Operation	Limit
POST /api/mcp/create	10 per hour
POST /api/custom-tools	15 per hour
POST /api/retrieval-rules	25 per hour
MCP endpoint, POST /api/mcp/{id}	200 per minute

A limited request returns 429 with a Retry-After header in seconds:

{ "error": "Too many requests. Please try again later." }

Indexing is asynchronous

Creating a server, adding a source, and refreshing all return as soon as the work is queued. A 200 means it was accepted, not that indexing finished. Poll GET /api/mcp/{id} and read each source's crawlStatus:

crawlStatus	Meaning
pending	Queued
crawling	Being indexed now
complete	Indexed and searchable
error	Could not be indexed. crawlError says why

The MCP endpoint answers immediately either way; it simply has less to search until indexing completes.