When something says no
What the common refusals mean and what to do next: console only, needs an admin, blocked by the gate, rate limited, a stale version. Every refusal says what happened and the next step; this page explains the codes.
Qaldy says no on purpose, and it says why. Every refusal in the console, the API, the command line and over MCP has the same three parts: what happened, why, and what to do next, plus a stable code for programs. This page explains the ones people meet first.
In the console and from an agent#
| You see | What it means | What to do |
|---|---|---|
console_only | A token (an agent, the CLI, CI) tried something only a signed-in person may do: change who has access, make a token, change a plan, delete a table. | Do it in the console, or ask the person who owns the token. This is by design, not a fault. |
approval_needs_console | A build or change reaches the internet, sends messages, uses AI, starts shared or has a webhook or form trigger. A token may approve only the plainest plans. | Open the link the message gives you and approve it in the console after reading the permission sentences. |
admin_approval_required, "Needs an admin to approve" | The app uses a connector or AI models, whose key an admin sealed. A member may not approve it. | Copy the request to a workspace admin. |
insufficient_scope | The token has the read scope and the route needs write. | Make a token with the scope you need (a person approves it in the browser). |
token_revoked, unauthorized | The token or session ended: revoked, expired, or the person left the workspace. | Sign in again: qaldy login, or reconnect the client. |
admin_only | A route for admins, such as the audit log. | Ask an admin, or use an admin's own token. |
manifest_changed | The plan you approved is not the plan on the server. Approval only ever builds the exact plan you were shown. | Plan again and read the new permission sentences. |
stale_version | The app moved to another version while you were looking at an older one. | Reload, then redo the change on the current version. |
last_owner | The workspace's last owner cannot leave or be removed. | Hand the workspace over to someone first (an owner does this on Team). |
rate_limited | Too many requests in a short time. The Retry-After header says how long. | Wait that long and try again. |
When an app is refused at the gate#
A run that ends Blocked was stopped by the gate, not by a bug. The run says which call and why. These are the reasons you will see:
| Reason | What it means | What to do |
|---|---|---|
action_not_declared | The app called a connector action that is not in its manifest. | Add the action in a new version, and approve it. |
action_not_supported | The gate does not forward that action at all (for example a Telegram method that could read the bot's whole inbox). | Use a supported action. See the connector's page. |
domain_not_allowed | The app tried to reach an address that is not on its list. | If it should, add the address with a reason in a new version. |
media_not_allowed | A Telegram photo or file URL that is not https on an allowed host. | Use an allowed host, or a file id from an earlier upload. |
connector_not_connected | No key is stored for that connector. | Connect it on Connectors. |
budget_exceeded | An AI app reached its monthly budget. | Raise the app's budget under Settings, then Models, or wait for next month. |
egress_blocked (HTTP 403) is the umbrella code for all of the above. The audit log has a row for each, with the reason, and the Security screen can filter to Blocked calls.
When an app is asleep, or a run is waiting#
| You see | What it means | What to do |
|---|---|---|
A calm page saying the app is resting (HTTP 503, Retry-After) | The workspace reached its spending cap, or this app reached its daily limit, or a flood put it to sleep for a few minutes. The page says which. | Raise the cap or the app's daily limit, or wait. Apps wake shortly after a hold is released (the design aim is about 15 seconds). |
A run that says it is waiting (held: true) | The runs allowance is used up. The run starts by itself, oldest first, when there is room, and is dropped after 24 hours. | Add capacity, or wait for the month to renew. |
queue_full (HTTP 429) | The workspace already has 1,000 runs waiting. | Raise the cap or fix what is flooding the queue. |
| "Temporarily unavailable" (HTTP 503) at an app you never opened before | Qaldy's API is down, and the gate only remembers people it has already seen. See When the control plane is down. | Wait. People who already opened the app are unaffected. |
tool_rate_limited | An agent called a published automation more than 30 times a minute. | Slow the agent down. |
In a Backend#
| You see | What it means | What to do |
|---|---|---|
origin_not_allowed | A web page called the data API from an address the project does not list. A new project allows none. | Add your site's address in the backend's Settings. |
policy_denied | No rule lets this caller do that. A table is private until a rule says otherwise. | Add a rule on the Access tab. The message gives an example sentence. |
policy_violation | A change would make a row stop matching the rule that allowed it. | Change something else, or ask for a rule that allows it. |
public_needs_person | A key or an agent tried to open a table to visitors. Only a person can, by typing the table's name. | Do it in the console. |
token_invalid | A sign-in token sent to the data API did not verify: wrong key, issuer, audience or expiry. | Check the keys and the claims you pinned under Access. |
column_not_found | The column does not exist, or the caller may not see it at all. Both look the same on purpose. | Check the name and the rules. |
Trials#
trial_limited means a try-it workspace tried something a trial may not do: connect a service, share, make a token or call a model. Keep the workspace to remove the limits. See Try it without an account.
Connectors#
| You see | What to do |
|---|---|
| Expired, reconnect or Not working, reconnect on a card | Replace the key with a fresh one from the provider. Press Test connection. |
| A test says the service refused the key (401) | The key was mistyped, revoked or regenerated. Replace it. |
| A first call to a Preview connector fails | It has not been run against a live account yet. Tell us what the service answered; see Connectors. |
Still stuck#
Message us on Telegram. A person reads every message. Quote the requestId from the error if there is one: it finds the exact request in our logs.