Skip to content
AlumiaDocs

Search docs

Find pages, headings, and concepts. Press ⌘K or Ctrl+K to toggle.

Troubleshooting

The errors you'll actually hit and exactly what to do about them.

Open in ChatGPTOpen in Claude

This is a working list of the failure modes most users see, what they look like in the UI and over the API, and the fix.

402 PAYMENT_REQUIRED

What you see. In the lab, a billing card appears in the chat panel explaining that managed credits are required before the paid operation can continue. Over the API, the response envelope is {"error":{"code":"PAYMENT_REQUIRED","message":"…"}} with HTTP status 402.

Why. The agent tried to run a managed model or metered platform operation, but the org has no usable credits, the active package blocks the operation, or an applicable budget is exhausted. BYOK model-token calls cost 0 Alumia credits, but package infrastructure caps can still apply.

Fix. Either:

  • Click Buy credits on the card, or open /<orgSlug>/billing and buy a top-up package there. See Top up credits.
  • Or switch model-token calls to BYOK where your package allows it.

Connector auth failed

What you see. On /<orgSlug>/connectors, the connector card shows Auth failed instead of Connected. Tools backed by it return an auth error when the agent calls them.

Why. OAuth refresh failed — typically the user revoked Alumia in the provider's account settings, changed their password, or the refresh token expired beyond the provider's window.

Fix. Click Reconnect on the connector card. The OAuth consent flow re-opens in a new tab. Sign in and re-grant scopes. The status flips back to Connected, and the next tool call succeeds.

If the problem is missing scope (the agent calls an operation you didn't authorise — for example gmail.send after granting only read scopes), reconnect with the broader scope rather than enabling the operation in agent settings.

429 TOO_MANY_REQUESTS

What you see. API responses with HTTP status 429, body {"error":"Too many requests","retryAfterMs":<n>}, and a Retry-After header in seconds.

Why. The chat endpoint enforces 60 requests per minute per user/IP. Other endpoints have their own limits.

Fix. Wait for Retry-After to elapse and retry. In code, back off exponentially keyed off the header. If you're hitting the chat limit at scale, consolidate calls onto a single session — replays of the same conversation cost one request, not N.

Agent stuck on a tool

What you see. On the canvas, the agent's session shows a tool call in progress that never finishes. The chat reply has stopped streaming.

Why. Three common causes:

  1. The tool itself is slow. Browser sessions waiting on a page load, sandbox commands running long, or external connector calls hitting upstream timeouts.
  2. The tool is waiting on a peer. If the agent called message_agent and is sitting in check_messages, it's waiting for a peer that may itself be busy or stalled.
  3. The model returned a malformed tool call that didn't match the tool schema, causing the runtime to retry.

Fix.

  • Open the tool call on the canvas and read the arguments and partial output. If it's an external service, look at the connector's status.
  • For a stuck peer chain, list participants with list_agents from the originator and check whether the peer is in awaiting_peer or idle. Send a follow-up message_agent if needed.
  • Cancel the session from the chat panel and restart with a tighter prompt. If the same tool fails the same way twice, the underlying tool is broken — disable it on the agent until the integration is fixed.

API key returns 403 on workspace or share routes

What you see. 403 ForbiddenError with copy like "requires a browser session" when calling workspace, project share, org membership, webhook/MCP/domain administration, skill, guardrail, org settings, memory delete, or account-security routes with an API key.

Why. These mutations are intentionally limited to stepped-up browser sessions to reduce automation risk on account-security surfaces.

Fix. Perform the action in the dashboard (you may be prompted for passkey or TOTP step-up), or use a different API that does not gate browser-only mutations. API keys remain valid for agents, chat, files, billing reads, and most operational APIs.

Top-up credits did not appear

What you see. You bought credits in the Billing dialog (native Stripe Elements) or completed a subscription Checkout redirect, but the credit total still shows the old amount.

Why. Stripe's webhook to Alumia hasn't landed yet, or the page didn't reload to pick up the new credit bucket. Billing top-ups use POST /api/v1/billing/top-ups/payment-intent.

Fix. Reload /<orgSlug>/billing. If the credits are still old after one minute, the webhook failed — open Billing → invoices and receipts to confirm the Stripe document status. Stripe's retry will land within a few minutes; the top-up eventually reconciles. If it doesn't within an hour, contact support with the Stripe receipt, PaymentIntent, or Checkout session ID.

401 UNAUTHORIZED on the API

What you see. Every API call returns 401.

Why. The Authorization: Bearer <key> header is missing, malformed, or the key was revoked.

Fix. Verify the key in /<orgSlug>/developers → API Keys is not revoked and resend with Authorization: Bearer alm_…. The org is derived from the key — no separate org header is required. If the key was rotated, regenerate it and replace it in your environment — keys are shown exactly once at creation.

404 on /share/<token>

What you see. A shared canvas link returns 404.

Why. Sharing was disabled on the project, the project was deleted, or the token in the URL is wrong.

Fix. Re-enable sharing on /<orgSlug>/projects/<projectSlug> (canvas toolbar → Share). The system mints a new token; share that URL. See Share a canvas.

Schedule run failed

What you see. A notification that a cron schedule failed, or no canvas activity at the expected time.

Why. The target agent was disabled, the workspace binding changed, the prompt hit a 402 balance error, or the agent tool chain stalled.

Fix. Open /<orgSlug>/notifications, read the schedule failure payload, then fix the agent model/balance or edit the schedule at /<orgSlug>/schedules. See Schedules guide.

Step-up auth expired

What you see. 403 when minting API keys, sharing a project, editing skills, or approving Agent Wallet spend right after you authenticated.

Why. Sensitive actions require fresh step-up (passkey or TOTP within about ten minutes).

Fix. Complete step-up again from Settings → Security, then retry the action. See Passkeys and 2FA.