DocumentationAPI & MCP

Errors and limits

The error codes, what they mean, and how many calls a minute.

An error answers { "error": { "code": "…", "message": "…" } } with its HTTP status. Over MCP, the tool error’s message is CODE: message. Branch on the code, not on the message.

Error codes

StatusCodeWhen
400INVALID_INPUTThe body or an argument doesn’t match the operation: details lists the fields at fault.
401MISSING_API_KEY, INVALID_API_KEY, EXPIRED_API_KEY, WORKSPACE_DELETEDNo key, an unknown or revoked key, an expired key, or its workspace was deleted.
402INSUFFICIENT_TOKENSA billed operation, and the workspace’s credits can’t pay for it.
403FORBIDDENThe key’s creator isn’t allowed to do this in the workspace: the same rule as in the app.
403PLAN_LIMIT_EXCEEDEDThe workspace’s plan doesn’t include it: on an account that has never paid, a competitor’s backlinks or a hidden competitor’s analysis.
404NOT_FOUNDNo such site, conversation, task… in this workspace.
409CONFLICTAlready running, or in a state that forbids it.
429RATE_LIMITEDToo many requests for the workspace: Retry-After says when to retry.
503SERVICE_UNAVAILABLEA service the operation needs is briefly unavailable: retry later.
500INTERNAL_ERROROur fault: retry later.
402
{
  "error": {
    "code": "INSUFFICIENT_TOKENS",
    "message": "Workspace is out of tokens for this period."
  }
}

Rate limits

Per workspace
API120 requests a minute
MCP30 tool calls a minute

Over the limit, the answer is 429 RATE_LIMITED, with a Retry-After header that says when to retry.

A question this doesn’t answer? Write to us.

Ready to get your site off the ground?

Ask your first question - semchat replies with a clear action plan in seconds.

Free · no sign-up · takes 5 seconds