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.
  • 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. The error includes the shop_id and the store’s dashboard_url: track the store there, then retry.

​
Service errors

​
search_unavailable

The search engine timed out or is temporarily down. Retry in a moment.

​
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.

​
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.