Errors and limits

Error shape#

Every error is JSON with a stable code and a plain message. Validation errors add the fields at fault.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input.",
    "details": [
      {
        "field": "items.0.label",
        "message": "Too small: expected string to have >=1 characters"
      }
    ]
  }
}

Codes#

• 401UNAUTHORIZEDNo key, or the key is unknown or revoked. Uploads always need a bearer key.
• 403FORBIDDENThe key works but its owner may not do this here, for example a viewer trying to upload.
• 404NOT_FOUNDNo such endpoint, workspace, company, run or industry, or one the key cannot see.
• 409CONFLICTThe request clashes with what exists.
• 422VALIDATION_ERRORThe input does not match the schema. details lists each field and what is wrong.
• 429TOO_MANY_REQUESTSToo many uploads from this key in the last minute. The message says when to retry.
• 500ERRORSomething went wrong on our side. Retry; if it persists, tell us.

Over MCP the same failures come back as a tool result with isError: true and text such as Error 404: Company not found. or Invalid input: items.0.label: ….

Limits#

• At most 200 items per upload call (components, flows or notes).
• At most 30 write calls per key every 60 seconds, across create and upload. Reads are not rate-limited here.
• Search returns at most 50 hits; validation errors list at most 20 fields.
• Re-uploading the same clientId updates instead of duplicating, so retrying a failed batch is safe.