> ## Documentation Index > Fetch the complete documentation index at: https://docs.copyfy.io/llms.txt > Use this file to discover all available pages before exploring further. # Errors > Every error the Copyfy MCP returns, what it means, and how to fix it. 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. ```json Tool error theme={null} { "error": { "code": "quota_exceeded", "message": "The monthly Copyfy MCP allowance is used up.", "used": 300, "limit": 300, "resets_at": "2026-10-10T00:00:00.000Z", "upgrade_url": "https://app.copyfy.io/dashboard/plans" } } ``` | Code | Summary | | ------------------------------------------------- | --------------------------------------------------------------------------- | | [`plan_upgrade_required`](#plan_upgrade_required) | Your plan does not include the MCP | | [`trial_not_eligible`](#trial_not_eligible) | Your subscription is in its free trial | | [`subscription_past_due`](#subscription_past_due) | Your last payment failed | | [`subscription_paused`](#subscription_paused) | Your subscription is paused | | [`account_restricted`](#account_restricted) | Your account is suspended | | [`quota_exceeded`](#quota_exceeded) | No credits left this month | | [`rate_limited`](#rate_limited) | Too many calls in a short time | | [`invalid_arguments`](#invalid_arguments) | An argument value is not recognized, or the arguments contradict each other | | [`not_found`](#not_found) | The store, product, or ad does not exist | | [`shop_not_tracked`](#shop_not_tracked) | The detail requires tracking the store | | [`search_unavailable`](#search_unavailable) | Search is temporarily down | | [`service_unavailable`](#service_unavailable) | Copyfy is temporarily unavailable | | [`internal_error`](#internal_error) | Unexpected 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](/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`](/tools/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: ```http Response (abbreviated) theme={null} HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer resource_metadata="https://app.copyfy.io/.well-known/oauth-protected-resource/mcp" ``` 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](/troubleshooting#401-unauthorized-or-the-client-keeps-asking-to-sign-in).