Skip to content

MCP errors

Every refusal of the DEBYKO MCP server is a tool result with isError and a body of the API’s shape, {"errors": [{"code", "message", "next", "retry", "retry_after"?, "docs"?}]}: code is what a program branches on, message says what happened, next is what to do now — written for the person, with the exact URLs and button names, and the AI is asked to give it as it is —, retry says whether the same call can succeed if it is repeated unchanged (and retry_after in how many seconds), and docs names the resource or page that explains.

The next below is the one the server gives when the error comes without its own. Many come with their own, more precise one: a plan limit names your plan’s numbers, a refused venue lists the venues your plan includes, a Telegram link that is waiting gives the time it expires.

Code What to do (next) Retry
UNAUTHENTICATED 1. Open https://studio.debyko.com/account/signin, enter your email and press Send the code, then enter the code from the email and press Sign in. The Free plan is free and needs no card. 2. An account opened by signing in on the sign-in page (or from the documentation, or from a plan button) shows its API key once, on the page Your account is open: press Copy; under the key the page has the first request, ready to paste with the key in it (an account opened by connecting an AI client with OAuth, or from Studio or Agent, has no key of its own until you make one). For another key later, open https://studio.debyko.com/account and under API keys press Issue a key (or open the ⋯ menu of the key you have and press Rotate, then Rotate key: a new key with the same label is shown once, and the old one stops working within 30 seconds). 3. Put the key in your MCP client as the header Authorization: Bearer <key>, or instead add https://mcp.debyko.com/mcp as a connector and sign in with OAuth (no key to copy). no
AUTH_REQUIRED 1. Open https://studio.debyko.com/account/signin, enter your email and press Send the code, then enter the code from the email and press Sign in. The Free plan is free and needs no card. 2. An account opened by signing in on the sign-in page (or from the documentation, or from a plan button) shows its API key once, on the page Your account is open: press Copy; under the key the page has the first request, ready to paste with the key in it (an account opened by connecting an AI client with OAuth, or from Studio or Agent, has no key of its own until you make one). For another key later, open https://studio.debyko.com/account and under API keys press Issue a key (or open the ⋯ menu of the key you have and press Rotate, then Rotate key: a new key with the same label is shown once, and the old one stops working within 30 seconds). 3. Put the key in your MCP client as the header Authorization: Bearer <key>, or instead add https://mcp.debyko.com/mcp as a connector and sign in with OAuth (no key to copy). (docs://getting-started) no
AUTH_INVALID 1. Open https://studio.debyko.com/account/signin, enter your email and press Send the code, then enter the code from the email and press Sign in. The Free plan is free and needs no card. 2. An account opened by signing in on the sign-in page (or from the documentation, or from a plan button) shows its API key once, on the page Your account is open: press Copy; under the key the page has the first request, ready to paste with the key in it (an account opened by connecting an AI client with OAuth, or from Studio or Agent, has no key of its own until you make one). For another key later, open https://studio.debyko.com/account and under API keys press Issue a key (or open the ⋯ menu of the key you have and press Rotate, then Rotate key: a new key with the same label is shown once, and the old one stops working within 30 seconds). 3. Put the key in your MCP client as the header Authorization: Bearer <key>, or instead add https://mcp.debyko.com/mcp as a connector and sign in with OAuth (no key to copy). (docs://getting-started) no
ACCOUNT_DISABLED Write to support@debyko.com. (docs://getting-started) no
KEY_IN_URL Never put the key in a URL; it travels as a header, and a key that was in a URL should be replaced in the account. no
ACCOUNT_REQUIRED 1. Open https://studio.debyko.com/account/signin, enter your email and press Send the code, then enter the code from the email and press Sign in. The Free plan is free and needs no card. 2. An account opened by signing in on the sign-in page (or from the documentation, or from a plan button) shows its API key once, on the page Your account is open: press Copy; under the key the page has the first request, ready to paste with the key in it (an account opened by connecting an AI client with OAuth, or from Studio or Agent, has no key of its own until you make one). For another key later, open https://studio.debyko.com/account and under API keys press Issue a key (or open the ⋯ menu of the key you have and press Rotate, then Rotate key: a new key with the same label is shown once, and the old one stops working within 30 seconds). 3. Put the key in your MCP client as the header Authorization: Bearer <key>, or instead add https://mcp.debyko.com/mcp as a connector and sign in with OAuth (no key to copy). (docs://getting-started) no
Code What to do (next) Retry
PLAN_LIMIT Retry with from no earlier than the error names (candles gives the request as retry_with; account says how far back), or change plan under Plan & billing at https://studio.debyko.com/account. (docs://plans) no
PAYMENT_REQUIRED This call needs a key or a payment: the body says what to pay, and with an API key it is not asked for. no
PAYMENT_MALFORMED The payment sent is not a valid x402 payment: build it again, or use an API key. no
RATE_LIMITED Wait retry_after seconds and call again; fewer calls, or a larger plan, raises the limit (the account tool shows the limits and what is left). (docs://plans) yes
PLAN_RULE_LIMIT Pause or delete a rule you no longer need (agent_rule_set, agent_rule_delete, or https://agent.debyko.com), or change plan under Plan & billing at https://studio.debyko.com/account. (docs://plans) no
PLAN_INTERVAL_TOO_SHORT Use a check interval at least as long as the plan’s shortest (docs://plans), or change plan under Plan & billing at https://studio.debyko.com/account. (docs://plans) no
PLAN_CHECK_BUDGET Use a longer check interval or pause another rule, or change plan under Plan & billing at https://studio.debyko.com/account. (docs://plans) no
PLAN_CHANNEL_LIMIT Remove a webhook or disconnect a Telegram chat at https://agent.debyko.com/channels, or change plan under Plan & billing at https://studio.debyko.com/account. (docs://plans) no
PLAN_NOTIFICATION_LIMIT Wait until 00:00 UTC (retry_after seconds), when delivery resumes on its own; rules keep running meanwhile, or change plan under Plan & billing at https://studio.debyko.com/account. (docs://plans) yes
Code What to do (next) Retry
AGENT_STOPPED Turn Agent on at https://agent.debyko.com (toggle ‘Agent is on’) or with agent_set_enabled when the user asks, and the rule runs. (docs://agent) no
AGENT_UNAVAILABLE Try again in a few minutes, and write to support@debyko.com if it keeps failing. yes
CHANNEL_REQUIRED Ask the user whether alerts should go to Telegram, email or a webhook, then call agent_channel_connect with that kind. (docs://agent) no
TELEGRAM_NOT_LINKED Call agent_channel_connect with kind telegram and give the user its steps, then call again once they pressed Start. (docs://agent) no
TELEGRAM_LINK_PENDING Ask the user to open the link agent_channel_connect gave and press Start in Telegram, then call again. (docs://agent) yes
TELEGRAM_UNAVAILABLE Try again in a few minutes, or use a webhook instead. yes
CHANNEL_DISABLED For Telegram ask the user to unblock @debyko_bot and connect again, for email call agent_channel_connect with kind email and have the user confirm it, for a webhook fix the receiver and press Send test. (docs://agent) no
CHANNEL_DAILY_LIMIT Use a channel the account already has (agent_channels lists them), or add the new one tomorrow. no
LABEL_REQUIRED Ask the user for a short name for this alert, the first line of every notification, and call again with it as label. no
RULE_PAUSED_BY_DEBYKO The rule resumes on its own once the reason in the message is gone; if the reason is the plan, change the rule or the plan (docs://plans). (docs://plans) no
Code What to do (next) Retry
DQL_ARGUMENT Give the argument a value inside the range the message states and call again. (docs://dql) no
DQL_AS_OF_RANGE Ask for an instant between the earliest retained data and now and call again. (docs://dql) no
DQL_COMPLEXITY Simplify the query (fewer series calls, shorter windows) and call again. (docs://dql) no
DQL_DUPLICATE_CLAUSE Give each clause once and call again. (docs://dql) no
DQL_JSON_SCHEMA A field of the request is not the shape the tool takes: correct the field named in path or in the message, and call again. (docs://dql) no
DQL_LIMIT Read the named limit: split listings without dropping products, or split an oversized time window, and retry; a shorter window does not fix too many listings. (docs://dql) no
DQL_NESTING Flatten the query: a quantifier cannot sit inside another one. (docs://dql) no
DQL_SCOPE Wrap the venue-scoped field in any(venues where …), all(…), count(…) or an aggregate, and call again. (docs://dql) no
DQL_SYNTAX Correct the query at the given position (the message says what was expected there, and docs://dql has the grammar) and call again. (docs://dql) no
DQL_TIMEFRAME_MISMATCH Read both series at the same period and call again. (docs://dql) no
DQL_TIMEFRAME_REQUIRED Add timeframe 1h (or another period) to the query, or give the series function its own period, and call again. (docs://dql) no
DQL_TIMEFRAME_UNSUPPORTED Use one of the periods the message lists and call again. (docs://dql) no
DQL_TYPE Change the operation to one the types allow (the hint says which fields can be summed or compared) and call again. (docs://dql) no
DQL_UNKNOWN_ASSET Write the base asset as the instruments tool shows it (BTC, not BITCOIN) and call again. (docs://dql) no
DQL_UNKNOWN_CURRENCY Write the quote currency as the instruments tool shows it (for example USDT) and call again. (docs://dql) no
DQL_UNKNOWN_FIELD Use a field the hint names or one listed in docs://dql, and call again. (docs://dql) no
DQL_UNKNOWN_FUNCTION Use a function the hint names or one listed in docs://dql, and call again. (docs://dql) no
DQL_UNKNOWN_INSTRUMENT Write the instrument as BTC-PERP, not BTC, taking it from the instruments tool, and call again. (docs://dql) no
DQL_UNKNOWN_VENUE Write a venue code exactly as the venues tool lists it and call again; the code you sent is no venue at all. (docs://dql) no
DQL_VERSION Leave dql out of the request, or send “1”, and call again. (docs://dql) no
Code What to do (next) Retry
ANCHOR_CHANGED Do not repeat the call: history changed after the anchor, which is what the anchor is for, and the day’s root and the proofs made before still stand. no
ANCHOR_NOT_FOUND Pick a day that is anchored (a day is anchored within 24 hours of its end) and a row that was stored; the message says which was missing. no
ANCHOR_NOT_YET The day is not on the chain yet: ask about the first anchored day the message names, or about this day again once it is anchored. no
NOT_FOUND There is nothing at this path: check the identifiers against what the listing tools return. no
UNAVAILABLE Wait a few seconds and call again; nothing in the request needs to change. yes
MCP_UNKNOWN_TOOL Call one of the tools this server lists. no
MCP_TOOL_UNAVAILABLE This tool has no endpoint yet: use another tool. no
MCP_UPSTREAM_UNREACHABLE The DEBYKO API could not be reached from here: wait a few seconds and call again. yes

UNAUTHENTICATED is the HTTP 401 of the MCP endpoint itself (no key or access token, or one that is not accepted); a client that signs in with OAuth signs in again by itself.