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. A new account shows its API key once, on the page Your account is open: press Copy. For another key later, open https://studio.debyko.com/account and under API key press Issue a key (or Revoke and issue new on the key you have; 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. A new account shows its API key once, on the page Your account is open: press Copy. For another key later, open https://studio.debyko.com/account and under API key press Issue a key (or Revoke and issue new on the key you have; 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. A new account shows its API key once, on the page Your account is open: press Copy. For another key later, open https://studio.debyko.com/account and under API key press Issue a key (or Revoke and issue new on the key you have; 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 |
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. A new account shows its API key once, on the page Your account is open: press Copy. For another key later, open https://studio.debyko.com/account and under API key press Issue a key (or Revoke and issue new on the key you have; 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 |
Ask for a later instant or a smaller window inside what the plan reads (the account tool says how far back), or change plan under Subscription at https://studio.debyko.com/account. (docs://plans) |
no |
PLAN_VENUE_NOT_INCLUDED |
Use one of the venues in your plan (the message lists them, and the account tool does too), or change plan under Subscription at https://studio.debyko.com/account (the plans are in docs://plans). (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 Subscription 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 Subscription 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 Subscription 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 Subscription 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 Subscription 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 or to 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 it again with agent_channel_connect; for a webhook fix the receiver and press Send test at https://agent.debyko.com/channels. (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 |
Narrow the request as the hint says (a narrower where, fewer layers or a shorter interval) and call again. (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.
