Skip to main content

    Error messages

    Plain-English explanations and fixes for the error codes Keypra surfaces — BYOK, credits, sanitiser, references, API gateway, and sessions.

    Troubleshooting
    Error messages

    Error messages

    What each error means, why it happens, and the quickest way out — grouped by where it shows up.

    Severity

    Critical — blocks the action
    Warning — degraded
    Info — coaching

    BYOK & AI routing

    BYOK_KEY_INVALID

    Your AI key is not working. Test & re-save.

    Cause

    A BYOK call hard-failed. The provider rejected the key, you edited the key without re-testing, or the master encryption version moved on.

    Fix

    Open the toast's Test & re-save action, or visit /settings/byok-rotation. Org keys: Org → AI Keys.

    BYOK_REQUIRED

    This workspace requires a working BYOK key (Strict mode).

    Cause

    Your org has Strict BYOK on. Keypra will never silently use a shared model in this org.

    Fix

    An org admin must store and validate a key per provider. See BYOK.

    MODEL_BLOCKED_BY_POLICY

    This model is not allowed by your organisation.

    Cause

    EU-only model policy is enforced for this AI feature, and the chosen model is non-EU.

    Fix

    Pick an EU-eligible model. See Data residency.

    Credits & billing

    INSUFFICIENT_CREDITS

    You are out of credits for this action.

    Cause

    Pre-flight checked your balance and there are not enough credits (1 Credit = 1,000 tokens).

    Fix

    Buy a Capacity Boost, upgrade your plan, or have your org top up. See Billing.

    CREDIT_GROUP_CAP_REACHED

    Your credit group has reached its cap for this period.

    Cause

    Your org admin set a per-group monthly cap and you have used it up.

    Fix

    Ask your admin to raise the cap or reassign you. See Members & credit groups.

    SUBSCRIPTION_OVERDUE

    Your subscription is overdue. Some features are paused.

    Cause

    A Stripe invoice failed and the grace window has passed.

    Fix

    Open the Stripe portal from Settings → Billing and update your card.

    Sanitiser & policy

    SANITISER_BLOCK

    This prompt was blocked by your org's content rules.

    Cause

    Your Compliance Steward set this category of content to block, not coach.

    Fix

    Rewrite the prompt or accept the inline suggestion. Ask the Steward if the rule needs tuning.

    SANITISER_COACH

    Suggestion: rewrite to remove sensitive content.

    Cause

    Teach-first mode flagged sensitive content but did not block.

    Fix

    Accept the inline suggestion or continue and learn — the event is logged anonymously for 30 days.

    References & embeds

    DOCUMENT_NOT_FOUND

    Referenced document does not exist.

    Cause

    The linked document was renamed, deleted, or lives in a Wing you no longer access.

    Fix

    Update or remove the reference. Use the Palace map to find orphans.

    BLOCK_NOT_FOUND

    Embedded block was not found.

    Cause

    The block ID was renamed or removed in the source document.

    Fix

    Re-insert with autocomplete (![[), or fix the source block ID.

    PERSONA_NOT_FOUND

    Persona could not be loaded.

    Cause

    The persona slug was renamed, archived, or moved out of your access scope.

    Fix

    Pick the persona again from the side panel; check spelling of the @slug.

    API gateway

    API_EXPERT_ONLY

    API access is gated to Expert.

    Cause

    Your account is on Free or Builder. Builder keys stop working after 6 May 2026.

    Fix

    Upgrade to Expert from Settings → Plan. See the API reference.

    INSUFFICIENT_SCOPE

    API key lacks the scope for this action.

    Cause

    The key was issued without (for example) <code>execute:workflow</code>.

    Fix

    Issue a new key with the right scopes in Settings → API Access.

    RATE_LIMIT_EXCEEDED

    Rate limit exceeded.

    Cause

    You exceeded 120 requests/minute or 20,000/day on Expert.

    Fix

    Back off using the Retry-After and X-RateLimit-Reset headers.

    Sessions & sync

    SESSION_EXPIRED

    Your session has expired. Please sign in again.

    Cause

    Your auth token rotated past its window.

    Fix

    Sign in again. If this happens often, allow third-party storage for keypra.com.

    CLASSROOM_OUT_OF_SYNC

    Slide is out of sync with the lecturer.

    Cause

    The realtime channel dropped briefly.

    Fix

    Click Re-sync in the toolbar, or refresh.