- Tool errors: the call reached Copyfy but was refused or failed. The result has
isError: trueand a JSON body with a stablecode, a readablemessage, and sometimes extra fields such as a link. Tool errors never cost a credit, except a creation tool’sservice_unavailablethat includes ajob_id. - HTTP 401: the request has no valid credential. Your client must sign in again or use a valid API key.
Tool error
Access errors
plan_upgrade_required
Your plan does not include the MCP: you are on Starter or have no subscription. The error includes anupgrade_url. Upgrade to Growth or Pro to use the MCP.
trial_not_eligible
Your subscription is still in its free trial. Access starts automatically when the trial ends and the subscription becomes active.subscription_past_due
Your last payment failed. The error includes amanage_subscription_url: update your payment method in billing settings and the MCP works again.
subscription_paused
Your subscription is paused. The error includes amanage_subscription_url: resume the subscription in billing settings.
account_restricted
Your Copyfy account is suspended or scheduled for deletion. Every tool is refused, includingget_usage. Contact Copyfy support.
Usage errors
quota_exceeded
You used all the credits of the current monthly period. The error includesused, limit, resets_at, and, on Growth, an upgrade_url. Wait for resets_at or upgrade to Pro. list_filter_options and get_usage keep working. See Quotas and limits.
rate_limited
Your account made more than 30 calls in one minute, or too many invalid keys were sent from your network. The error includesretry_after_seconds: wait that long, then retry.
Request errors
invalid_arguments
An argument value is not recognized by Copyfy, such as an unknown niche name, or the arguments can never match: a range whosemin is above its max (or from after to), active_days with status: "inactive", or get_shop with both shop_id and domain. The message names the argument and how to fix it. Use list_filter_options for valid values.
Arguments that break the tool’s schema (a wrong type, page above 20, an unknown enum value) are rejected by the MCP layer before Copyfy runs the tool. The client gets isError: true with a plain-text validation message instead of the JSON body above. These calls are free too.
not_found
The store, product, or ad does not exist in Copyfy. Check the id or domain, and take ids from a search result.shop_not_tracked
The detail you asked for requires tracking the store, as in the dashboard.get_product returns it only for a product Copyfy no longer lists; for other stores you do not track, it returns a short product sheet instead. The error includes the shop_id and the store’s dashboard_url. Ask your assistant to track the store with track_shop, or track it in the dashboard, then retry. share_tracked_shops also returns this code, with untracked_shop_ids, when you ask it to share stores you do not track.
shop_not_trackable
track_shop cannot track this site. The reason field says why: marketplace_unsupported (Amazon, Etsy, and other marketplaces), unsupported_site, not_ecommerce_store, no_physical_products_detected, service_business, digital_products_only, insufficient_store_evidence, shop_blacklisted (restricted by Copyfy’s safety policy), store_blocked (the store blocks automated access), store_unreachable, or admission_unavailable. The last three can change: retry later.
tracking_limit_reached
All the tracking slots of your plan are used. The error includeslimit, a tracked_shops_url to manage your tracked stores, and, on Growth, an upgrade_url. Stop tracking a store with untrack_shop, or upgrade to Pro.
Credit and connection errors
insufficient_credits
generate_ad_image or copy_video_ad needs more AI credits than your account has. Nothing is generated or charged. The error includes required_credits, remaining_credits, and buy_credits_url: the AI credit packs on the Plans page, or your billing settings when your subscription is billed through Shopify.
cost_limit_exceeded
The generation would cost more AI credits than themax_ai_credits you passed. Nothing is charged. The error includes required_credits and max_ai_credits.
paid_plan_required
Image and video generation needs an active paid plan, as in the dashboard. Accounts in a trial get this error; the error includes anupgrade_url.
shopify_not_connected
import_product_to_shopify needs a Shopify store connected to your Copyfy account. The error includes connect_url: connect the store, then try again.
shopify_reconnect_required
Shopify refused Copyfy’s access to your store, usually because the connection expired or lacks the permission to create products. The error includesshop_domain and reconnect_url, which opens the reconnection flow that matches how the store was connected.
Service errors
media_unavailable
Copyfy could not download the image you passed, for example tofind_product_by_image, or the product or ad media a generation needs. Check that the link is public and points directly to a JPEG, PNG, or WebP image. For copy_video_ad, the ad has no video stored by Copyfy: pick an ad whose video_url is set. The call is free.
search_unavailable
The search engine timed out or is temporarily down. Retry in a moment.feature_unavailable
The feature behind the tool is switched off or not published right now, for example Marcuus’s product picks between two selections. The call is free; try again later.service_unavailable
Copyfy could not check your credential because of a temporary outage. Your credential is still valid: retry in a moment, and do not delete or rotate your key. A creation tool also returnsservice_unavailable when its job cannot start. When the error includes a job_id, Copyfy could not confirm whether the job started: call get_job_status with that id before trying again, so nothing is created twice. The call’s MCP credit stays set aside until the job ends: kept if the job ran, given back if it did not.
A search, detail or analysis tool returns service_unavailable with retry_after_seconds when Copyfy takes too long to answer. Nothing is charged: retry in a moment.
result_too_large
The response exceeds 64 KiB. No MCP credit is charged and no results are silently dropped. Narrow the filters or request fewer items. For searches, the 20-page limit still applies: a smallerper_page reduces the reachable results. Narrow the filters to recover later matches. If you change per_page, restart pagination and deduplicate earlier results.
internal_error
An unexpected error happened on Copyfy’s side. Retry. If it persists, contact support with the time of the call.HTTP 401 Unauthorized
Copyfy returns HTTP401 when the Authorization header is missing, malformed, expired, or revoked. The response includes a WWW-Authenticate header that points to Copyfy’s OAuth metadata:
Response (abbreviated)
cpy_, and has not been revoked. See Troubleshooting.