Refine Docs

MCP server

Errors & limits

Knowing how the server pushes back helps you build resilient integrations. Here’s every limit it enforces and how failures surface.

Limits at a glance#

LimitValue
Requests per API key60 / minute (fixed window)
Active API keys per account20
Monitored prompts per brandVisibility 50 · Autopilot 200
Generated items per brand30 / month per content type
Publishing cadence (agent loop)1 article every 2–5 days
Max request duration300 seconds

Authentication errors#

Requests without a valid key are rejected with HTTP 401 before any tool runs. Common causes:

  • Missing or malformed Authorization header.
  • A key that doesn’t start with rfn_live_.
  • A key that has been revoked, or whose brand was deleted.

See Authentication to fix these.

Tool errors#

Once you’re authenticated, errors are returned inside the MCP response with isError: true rather than as an HTTP error — so your client sees a clean, human-readable message:

error result
{
  "content": [
    { "type": "text", "text": "Rate limit exceeded. Try again in a minute." }
  ],
  "isError": true
}

You’ll see these for:

  • Plan gating — calling a tool your plan doesn’t cover. The message names the required plan and links to upgrade.
  • Rate limiting — more than 60 requests in a minute on one key.
  • Validation — invalid arguments (e.g. a malformed UUID or a color that isn’t a hex code).
  • Not found — referencing a prompt, tag or competitor that doesn’t belong to the key’s brand.

Rate limiting#

Each key is limited to 60 requests per minute on a fixed window that opens with the first call. When you exceed it, every call returns the rate-limit error above until the window closes, up to a minute later. Retrying sooner does not help: wait out the minute, then resume. Calls refused this way count as calls, so a tight retry loop only extends the wait.

Use one key per client: the limit is per key, so a scheduled agent and a person chatting do not eat into each other’s budget.

Messages worth handling#

Messages are written for the person reading the chat, so an assistant can usually relay them as is. These are the ones an integration should branch on. Each tool’s own errors are listed with it in the tools reference.

Message starts withWhat to do
Wait for the minute to pass, then retry.
The brand owner has no active plan. Nothing to retry.
The tool needs Autopilot. Read-only tools still work.
The brand used its 30 items of that type this month. Retry on the 1st.
Delete a prompt or move to Autopilot (200).
The id belongs to another brand, or was deleted. Re-list before acting.
Generation is unfinished. Keep polling get_content.
Ask the customer to connect WordPress or Webflow in Settings.
Call publish_article again with an explicit target.
The application password was revoked. The customer must reconnect.
The customer has not connected that Google product in Settings.
The authorisation was revoked or expired. The customer must reconnect it.
Google refused the request, usually a property the account cannot read.

Invalid arguments (a malformed UUID, a days value outside its list, a color that is not hex) are rejected by the MCP layer before the tool runs, with the schema’s validation message.

Content generation rules#

Content generation is asynchronous: generate_content returns a contentId immediately, and you poll get_content until its status is complete. A few rules apply:

  • Each brand can generate 30 items per content type per calendar month (blog articles, Reddit replies and LinkedIn posts are counted separately). Failed generations do not count.
  • Any sourceUrls you pass are validated against SSRF — only public http/https URLs are fetched. Private IPs, localhost and cloud metadata endpoints are rejected.

Polling tip

Poll get_content every few seconds rather than in a tight loop — generation takes time, and tight polling burns your rate-limit budget. The progress field tells you how far along it is.