Docs · errors & limits

Errors & limits

Every failure sets the MCP isError flag and its text starts with “error: <code>”, usually followed by what to do about it. Your assistant never has to parse prose to know what went wrong.

( Error codes )

• validation_failedAn argument is missing or the wrong shape. The message names the field.
• project_not_foundNo project with that id in your organization. Call list_projects and match by name.
• competitor_not_foundNo competitor with that id in that project. Call list_competitors.
• account_not_foundNo tracked account matches that url. Call list_tracked_accounts and pass the url exactly as stored.
• platform_mismatchThe handle belongs to a different platform than the method you called.
• handle_not_recognizedThe string is not a profile link or handle the server recognizes.
• feature_not_grantedThe organization's plan does not include this data source.
• limit_reachedA plan cap was hit: projects, competitors or tracked accounts.
• trial_expiredThe organization's trial ended.
• rate_limitedThe hourly budget for this connection is spent. The message says when it resets.
• upstream_failedA dependency failed mid-call. Safe to retry.
• server_errorOur fault. Retrying with the same arguments is safe; if it persists the app shows the same data.

Auth failures (expired or revoked tokens) have their own codes, listed on the authentication page.

( Rate limits )

• ›Hourly, per connection: 300 read calls and 60 write calls, counted separately, so a chatty read loop cannot exhaust the ability to write.
• ›The draft methods (prepare_create_project, prepare_add_competitor) write nothing but charge the write bucket: they scrape and call a model, which is a different cost than a database read.
• ›A spent bucket returns rate_limited with the reset time in the message. Waiting is the only fix; retrying earlier just spends nothing.

( Timing expectations )

• ›Reads answer in under a second. The prepare methods scrape and reason, so they take seconds; never retry one that is still running.
• ›Writes queue background collection. A new competitor's news, reviews and posts arrive over the following minutes, and the response says exactly which jobs were dispatched.