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 yellow card appears in the chat panel titled Your balance is empty with the message "Add funds to your billing balance before running paid models." Over the API, the response envelope is {"error":{"code":"PAYMENT_REQUIRED","message":"…"}} with HTTP status 402.

Why. The agent ran a paid model and the org's USD balance is at zero. Free visible providers such as Groq and NVIDIA do not trigger this; only paid providers do.

Fix. Either:

  • Click Add funds on the card, or open /<orgSlug>/billing and add funds there. See Top up your balance.
  • Add a BYOK key for that provider so the request stops drawing from the Alumia balance. See BYOK.
  • Or pick a free provider's model in the agent settings.

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.

Stripe checkout did not return a balance

What you see. You completed Stripe checkout, the page redirected back, but the balance pill 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 balance.

Fix. Reload /<orgSlug>/billing. If the balance is still old after one minute, the webhook failed — open Settings → Billing → recent activity and confirm the deposit's status. Stripe's retry will land within a few minutes; the deposit eventually reconciles. If it doesn't within an hour, contact support with the Stripe checkout session ID.

401 UNAUTHORIZED on the API

What you see. Every API call returns 401.

Why. Either the Authorization: Bearer <key> header is missing, the key was revoked, or you didn't include X-Alumia-Org: <orgSlug>.

Fix. Verify the key in /<orgSlug>/settings → API keys is not revoked, and resend with both headers. 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>/lab/<projectId>. The system mints a new token; share that URL. See Share a canvas.