Skip to content

Troubleshooting

Symptoms, causes and fixes for authentication, missing Pools, limits and evidence.

Updated View as Markdown
For humans

Find the symptom, then the cause. Every answer here names the object that actually decides the outcome, so you can check it directly.

401 from the Gateway

Cause: the key is missing, malformed, revoked, issued for another Environment, or belongs to another Home Cloud.

Fix: send Authorization: Bearer <key>, confirm the key still appears in API keys for the Environment you are calling, and confirm the Home Cloud of the Workspace matches the key.

My Pool is missing from GET /v1/models

Cause: the key does not list only what it can call. A Pool disappears when the key lacks the grant, the Pool is paused, the Agreement does not cover the capability, the provider connection is unusable, or the fallback policy cannot be satisfied.

Fix: check the Pool’s status and grants first, then the provider connection, then the entitlement for that capability.

429 quota_runtime_rate_limit_exceeded

Cause: the Pool’s requests-per-minute limit, or a per-key limit, was reached.

Fix: wait for the window to reset, raise the limit deliberately, or split traffic across keys. Retrying immediately makes it worse.

429 quota_hard_budget_exceeded

Cause: the Pool’s remaining hard budget cannot cover the request. The error body carries the limit and the remaining amount.

Fix: raise the Pool budget, wait for the next period, or move a low-priority workload to another Pool. The Gateway refuses the request rather than serving it on credit.

The console shows Unavailable

Cause: the snapshot carries no evidence for that interval, scope or field yet.

Fix: check the window and the selected Pool. AI Runtime does not print a zero for a period it never observed, and does not draw a chart from a single observation.

I need the exact request that failed

Use the requestId from the error body, or the x-airuntime-request-id response header, and open Requests in the console. Idempotent replays keep the first Request ID, so a retry does not hide the original attempt.

Codex does not offer my model

Cause: Codex sends the model name from its catalog, and that name must be a Pool slug the key may call.

Fix: compare the model value in ~/.codex/config.toml with the Pool slug, then confirm GET /v1/models returns it for the same key. Integrate with Codex walks through the file.

Still stuck?

Use the contact form, or write to support@gridheap.com, with the Workspace id, the Pool slug, the UTC time and the requestId. Never send prompts, outputs, credentials or customer payloads.

Type to search…

↑↓ navigate↵ selectEsc close