> ## Documentation Index > Fetch the complete documentation index at: https://docs.nexalytica.com/llms.txt > Use this file to discover all available pages before exploring further. # Errors & What They Mean in Nexalytica > A plain-language reference for every error you might see in Nexalytica — NX codes for agent failures, policy denials, account & billing states, and common action errors. When something can't be done, Nexalytica tries to tell you plainly what happened and what to do next. This chapter is a reference for every error you might run into, organised by where it shows up. For each one you'll find **what you see**, **what it means**, and **what to do** — plus the exact code, so you can quote it to support if you ever need to. Errors appear in four places: * **Under a chat reply** — when an AI agent can't finish, its answer is replaced by a short message and a small grey code badge in the form **`NX: · `** (for example, `NX:201 · AI Provider`). The number is a permanent reference; the category tells you which system was involved. * **As a toast (pop-up)** — quick actions like sharing, uploading, or changing a plan show a brief message at the corner of the screen if they're blocked or fail. * **As a banner** — organisation-wide states (trial ending, payment overdue, read-only) show a coloured strip across the top of the app. * **As a dialog** — a few states open a full pop-up you must read, such as "Credits Exhausted" or a suspended-organisation screen. Behind the scenes every error carries a short machine `code` (like `policy_denied` or `insufficient_credits`) and a human message. You never need the machine code, but it's included below so a support request can be precise. Raw technical detail (such as a provider's internal message) is deliberately never shown to you — it stays in the server logs for administrators. *** ## AI chat & agent failures — the NX codes When an agent run fails, the reply carries an `NX` code. There are three families: **1xx** = the agent itself, **2xx** = the external AI provider, **9xx** = the platform. This is the complete list. | Code | You see (the message under the reply) | What it means | What to do | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | **NX:101 · Agent** | "The agent ran out of working steps before it could finish. Try a more specific request, or break the task into smaller parts." | The agent hit its limit on reasoning steps for one request before reaching an answer. | Narrow the question or split it into smaller parts, then send again. | | **NX:102 · Agent** | "This request was waiting on your answer and expired before one arrived. Send the message again to start over." | The agent asked you a clarifying question and the run waited too long for your reply. | Send the message again to start a fresh run. | | **NX:103 · Agent** | "This request can no longer be resumed. Send the message again to start over." | A paused conversation can't be picked back up (for example, too much time passed). | Send the message again to start over. | | **NX:201 · AI Provider** | "The AI service is temporarily unavailable. Your organisation's administrators have been notified — please try again later." | The organisation's AI credits with the model provider are exhausted. | Your admins are alerted automatically (once per hour). Wait, or ask an admin to top up. | | **NX:202 · AI Provider** | "The AI service is busy right now. Please wait a moment and try again." | The AI provider is rate-limiting requests (too many at once). | Wait a moment and try again. | | **NX:203 · AI Provider** | "The AI service couldn't complete this request. Please try again." | The AI provider returned an error or couldn't be reached. | Try again; if it persists, tell an admin. | | **NX:901 · System** | "Something went wrong while processing your request. Please try again." | A catch-all internal error (also used when the cause can't be identified). | Try again; if it keeps happening, contact support with the time it occurred. | **NX:201** is the only failure that automatically notifies your organisation's admins by in-app alert and email, throttled to one notice per organisation per hour so they aren't flooded. **NX:101** also gets special handling: before failing, the agent makes one final attempt to write up whatever it has, so you often get a partial answer instead of a hard error. *** ## "Blocked by policy" — the Data Control Plane If your organisation's admins have armed a governance policy, an action that breaks it is stopped with a **"Blocked by policy"** toast (or, mid-chat, a note on the reply). The action simply doesn't happen, the attempt is recorded for admins, and admins are notified. The machine code is always `policy_denied`. There are 25 possible policies, grouped by what they protect. **Live-blocking** policies (marked ●) stop the action in the moment; the others watch in the background and raise a flag or alert instead of blocking you. ### Privacy | Policy | What it does | Severity | | ---------------------------- | ---------------------------------------------------------------------------------------- | -------- | | ● PII Column Access Control | Blocks an agent from reading columns marked as personal/sensitive data. | Critical | | ● External Sharing PII Block | Blocks sharing resources containing sensitive data with people outside the organisation. | Critical | | PII Review SLA | Flags detected personal-data columns that haven't been reviewed in time. | High | | Data Retention Compliance | Requires sensitive resources' retention posture to be re-verified periodically. | High | ### Security | Policy | What it does | Severity | | ------------------------------ | ----------------------------------------------------------------------------------- | -------- | | ● SQL Write Protection | Forces agent queries to be read-only and prevents reaching another source's tables. | Critical | | ● Restricted Table Access | Blocks agent queries against specific off-limits tables. | High | | ● Schema Drift Prevention | Quarantines a source whose structure changes unexpectedly. | High | | ● Hard Delete Protection | Blocks instant permanent deletion, forcing everything through recoverable Trash. | High | | Row-Level Security Enforcement | Requires row-level security to be in place on shared sources of certain kinds. | Critical | | Credential Rotation Policy | Flags data-source credentials that haven't been rotated recently. | High | ### Governance | Policy | What it does | Severity | | ------------------------------------- | ------------------------------------------------------------------------------------- | -------- | | ● Organisation Daily Spend Cap | Blocks new agent runs once the org's daily AI spend hits the cap. | High | | ● User Daily Run Cap | Blocks a person from starting more runs once they hit their daily limit. | Medium | | ● Model Allowlist | Restricts runs to an approved subset of AI models. | Medium | | ● Tool Usage Restriction | Blocks specific tools from being used by agents. | Medium | | ● Connector Allowlist | Restricts which kinds of data source can be connected. | Medium | | ● Cross-Source Join Control | Controls whether one query may join across different data sources. | Medium | | ● Organisation-Wide Share Restriction | Blocks org-wide shares, forcing deliberate per-person/department grants. | Medium | | ● Share Expiry Required | Requires (or shortens) an expiry on external share links. | Medium | | ● Public Dashboard Link Control | Disables or time-limits public dashboard links. | High | | ● File Upload Restrictions | Rejects uploads that are too large or of a disallowed type. | Medium | | Agent Query Cost Limits | Flags agent runs whose cost exceeds a per-run credit budget. | Medium | | Agent Daily Spend Auto-Suspend | Auto-suspends an agent whose own daily spend goes over its cap, pending admin review. | High | ### Quality | Policy | What it does | Severity | | --------------------- | ------------------------------------------------------------------------------------ | -------- | | ● Query Row Limit | Rejects a single agent query that would return more than the allowed number of rows. | Low | | Data Freshness SLA | Alerts when a source hasn't synced within its freshness window. | High | | Stale Sync Auto-Pause | Auto-pauses a source that hasn't synced successfully for too long. | Medium | If you hit one of these, the fix is usually to adjust your request (smaller query, allowed tool/model, non-external share) or to ask an admin, who can see and tune the policy in **Settings → Control Plane → Policy Engine**. *** ## Account & billing states These affect the whole organisation and are managed by billing admins. Most show as a banner across the top of the app; a couple open a dialog. | State (code) | You see | What it means | What to do | | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- | | Trial active | Grey/amber/red trial banner counting down days left, with **Upgrade now**. | You're on a free trial. It's neutral early, amber at ≤3 days, red and non-dismissible on the last day. | Add a plan before it ends to keep working. | | Payment failed — grace (`payment_failed`) | Red, non-dismissible banner: "Payment failed. Update your card to avoid losing access," with a countdown and **Update card**. | A charge was declined but you still have full access for a short window. | Update the card; access continues automatically once a charge succeeds. | | Read-only | Amber, non-dismissible banner: "Read-only mode — your payment is overdue…," with a countdown and **Update card**. | The grace window passed. You can view everything but not create or edit. | Update the card to restore full access. | | Plan required (`plan_required`) | You're sent to the plan picker. | No active plan is in place. | Choose a plan (billing admins only). | | Trial expired (`trial_expired`) | "Your trial has ended. Please choose a plan to continue." | The trial is over with no plan chosen. | Pick a plan. | | Trial already used (`trial_already_used`) | "This organisation has already used its trial." | A trial can only be started once per organisation. | Choose a paid plan instead. | | Plan limit reached (`plan_limit_reached`) | "Your plan's usage limit has been reached." | You've hit a ceiling your plan sets (dashboards, sources, users, storage, etc.). | Upgrade the plan or remove some usage. | | Credits exhausted (`insufficient_credits`) | A **"Credits Exhausted"** dialog: "…used all available credits for this billing period. Upgrade your plan or wait for the next cycle…" with a usage bar and **Manage Billing**. | The organisation's AI credit allowance for the period is gone. | Upgrade, or wait for the next billing cycle. | | Payment needs authentication (`payment_action_required`) | An extra card-verification prompt appears in-page. | Your bank asked for extra confirmation on the charge. | Complete the verification. | | Card required (`payment_method_required`) | "Cannot switch to a paid plan without a payment method. Please add a card first." | You tried to move to a paid plan with no card on file. | Add a card, then switch. | | Membership suspended (`membership_suspended`) | A full-screen **"Access blocked"** page: "Your membership for {org} is suspended…," with buttons to switch organisation or sign out. | Your access to this specific organisation was suspended by an admin. | Switch to another organisation, or contact that org's admin. | | Organisation suspended (`org_suspended_by_admin`) | "This organisation has been suspended. Contact support." | The whole organisation is suspended. | Contact support. | *** ## Common action errors Everyday actions can fail for ordinary reasons. These show as a toast with a short message; the machine `code` is in brackets. | You see | What it means | What to do | | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | "No active agent is configured for this conversation. Pick an agent in the composer, or activate a default agent for your department." (`no_agent_configured`) | You tried to send a chat message with no agent selected and no department default set. | Pick an agent in the composer, or ask an admin to set a default agent for your department. | | "This conversation is waiting for your answer to a clarifying question. Answer it (or cancel the run) before sending a new message." (`clarification_pending`) | The agent asked you something and is waiting; you can't send a new message until you respond. | Answer the pending question, or cancel the run. | | "This request can no longer be resumed. Send the message again to start over." (`clarification_not_resumable`) | The paused conversation expired. | Send the message again to start fresh. | | "Sign-ups with temporary, disposable, or email-relay addresses aren't allowed. Please use a permanent personal or work email address." (`blocked_email_domain`) | You tried to sign up with a throwaway/relay email. | Use a permanent personal or work email. | | "Your membership for this organisation is suspended." (`membership_suspended`) | As above — access to this org is suspended. | Switch organisations or contact an admin. | | A field-specific validation message (`validation` / `unprocessable`) | A form field was missing or invalid (for example, an invalid image URL on your profile). | Fix the highlighted field and save again. | | "Resource conflict." (`conflict`) | The action clashed with the current state (for example, something already exists). | Refresh and try again; the item may already be there. | | A "not found" or "you don't have permission" message (`not_found` / `forbidden`) | The item was moved/deleted, or you lack access to it. | Check you still have access; the owner may have changed sharing or deleted it. | Every one of these follows the same shape internally — a code, a plain message, and optional details — so the wording you see is always the specific, human explanation, never a raw technical dump.