> ## Documentation Index
> Fetch the complete documentation index at: https://docs.astrolabe.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Diagnose Cloud auth, billing, stack resolution, policy blocks, rate limits, and unbillable requests.

Always capture `x-astrolabe-cloud-request-id` when debugging. It links the gateway response to route traces, usage rows, model-call records, and operational events.

## Unauthorized

Symptoms:

* HTTP `401`
* error code `unauthorized`
* message says bearer authentication is required or the gateway key was not found

Fix:

* Send `Authorization: Bearer <ASTROLABE_CLOUD_KEY>` or `x-api-key`.
* Confirm the key was copied from the Cloud app.
* Confirm the key has not been revoked.

## Payment required

Symptoms:

* HTTP `402`
* error code `payment_required`
* message references prepaid balance

Fix:

* Add credits in Billing.
* Wait for checkout completion and ledger credit.
* Reduce request size or choose a lower-cost stack if the reservation is too large.

## Rate limited

Symptoms:

* HTTP `429`
* error code `rate_limited`
* `x-ratelimit-remaining: 0`

Fix:

* Back off until the `x-ratelimit-reset` timestamp.
* Use separate keys for separate services if traffic should be isolated.

## Stack not found

Symptoms:

* HTTP `404`
* error code such as `routing_stack_not_found` or `routing_stack_resolution_failed`

Fix:

* Check `metadata.astrolabe.stack`.
* Confirm the stack slug exists in the workspace.
* Confirm the selected version is active.
* Remove the request override to fall back to key, workspace, or managed default assignment.

## Routing policy blocked

Symptoms:

* HTTP `409`
* error code `routing_policy_blocked`
* message says no allowed candidates remain after applying stack boundaries

Fix:

* Check allowed and blocked providers.
* Check allowed and blocked models.
* Check required capabilities.
* Check max expected cost.
* Check whether fallback is required to stay inside policy.
* Inspect rejected candidates in the route trace.

## Unknown model or pricing model

Symptoms:

* HTTP `404` or `502`
* error code `unknown_model`, `unknown_pricing_model`, or similar

Fix:

* Use `GET /v1/models` to confirm public model IDs.
* Prefer virtual models such as `astrolabe/auto`.
* If requesting a concrete model, confirm it is active in the hosted model catalog.

## Structured output invalid

Symptoms:

* HTTP `502`
* error code `structured_output_invalid`

Fix:

* Use `astrolabe/strict-json`.
* Use the `strict-json` stack.
* Set `metadata.astrolabe.verification` to `strict` or `strong`.
* Inspect the route trace to see whether schema recovery ran.

## Unbillable usage

Unbillable records are expected for some failures. Astrolabe records them so operators can distinguish provider cost, customer billing, and rejected traffic.

Common unbillable reasons:

* `missing_provider_usage`
* `streaming_provider_error`
* `origin_unreachable`
* `unknown_pricing_model`
* `structured_output_invalid`
* tool or policy rejection codes

Unbillable requests should not debit customer balance.

## Support checklist

Send support:

* `x-astrolabe-cloud-request-id`
* timestamp
* endpoint
* requested model
* stack slug if used
* response status
* error code
* relevant response headers