Skip to main content
Copyfy reports problems in two ways:
  • Tool errors: the call reached Copyfy but was refused or failed. The result has isError: true and a JSON body with a stable code, a readable message, and sometimes extra fields such as a link. Tool errors never cost a credit, except a creation tool’s service_unavailable that includes a job_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 an upgrade_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 a manage_subscription_url: update your payment method in billing settings and the MCP works again.

subscription_paused

Your subscription is paused. The error includes a manage_subscription_url: resume the subscription in billing settings.

account_restricted

Your Copyfy account is suspended or scheduled for deletion. Every tool is refused, including get_usage. Contact Copyfy support.

Usage errors

quota_exceeded

You used all the credits of the current monthly period. The error includes used, 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 includes retry_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 whose min 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 includes limit, 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 the max_ai_credits you passed. Nothing is charged. The error includes required_credits and max_ai_credits. Image and video generation needs an active paid plan, as in the dashboard. Accounts in a trial get this error; the error includes an upgrade_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 includes shop_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 to find_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 returns service_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 smaller per_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 HTTP 401 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)
OAuth clients use this header to start the sign-in flow again. If you use an API key, check that it is copied in full, starts with cpy_, and has not been revoked. See Troubleshooting.