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.