# 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.

URL: https://docs.qaldy.com/getting-started/troubleshooting/

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](https://docs.qaldy.com/guides/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](https://docs.qaldy.com/concepts/bad-day/). | 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](https://docs.qaldy.com/getting-started/try-it/).

## 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](https://docs.qaldy.com/connectors/). |

## Still stuck

[Message us on Telegram](https://t.me/tairqaldy). A person reads every message. Quote the `requestId` from the error if there is one: it finds the exact request in our logs.