Troubleshooting

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