Skip to main content
Use this page as a step-by-step diagnostic playbook.

​
Fast triage flow

  1. Check GET /health first.
  2. Confirm inbound auth behavior.
  3. Run one known-good non-stream request.
  4. Inspect x-astrolabe-* response headers.
  5. Inspect server logs for route and model decisions.

​
Missing OPENROUTER_API_KEY

What it means: Astrolabe cannot call upstream models. Fix:
  1. Set OPENROUTER_API_KEY in .env or deployment env vars.
  2. Restart the process.
  3. Re-check /health and retry request.

​
401 unauthorized

What it means: inbound key does not match ASTROLABE_API_KEY. Fix:
  1. Send Authorization: Bearer <your_astrolabe_key> or x-api-key.
  2. Verify there is no trailing whitespace in env value.
  3. Confirm client and server are using the same key.

​
rate_limit_exceeded

What it means: request volume exceeded configured budget while ASTROLABE_RATE_LIMIT_ENABLED=true. Fix:
  1. Wait for retry-after seconds and retry.
  2. Increase ASTROLABE_RATE_LIMIT_MAX_REQUESTS.
  3. Increase ASTROLABE_RATE_LIMIT_WINDOW_MS.
  4. Disable limiter if needed for trusted/private traffic.

​
high_stakes_confirmation_required

What it means: high-stakes signal detected while ASTROLABE_HIGH_STAKES_CONFIRM_MODE=strict. Fix:
  1. Resend with x-astrolabe-confirmed: <token>.
  2. Or include metadata.astrolabe_confirmed: "<token>" in request body.
  3. Ensure token matches ASTROLABE_HIGH_STAKES_CONFIRM_TOKEN exactly.

​
invalid_json or payload_too_large

What it means: request body is malformed JSON or exceeds payload limit. Fix:
  1. Validate JSON before sending.
  2. Ensure messages is present and valid.
  3. Reduce payload size if request is too large.

​
Need full JSON instead of SSE

What it means: streaming is default. Fix:
  • send "stream": false in request body

​
Upstream OpenRouter errors

What it means: Astrolabe reached upstream but provider/model call failed. Check:
  1. Key validity and account credits.
  2. Model availability at provider.
  3. Payload shape compatibility.
  4. OpenRouter status.
Astrolabe retries retryable model/provider errors across fallback candidates when available.

​
Unexpected routing choice

What it means: policy interpreted request differently than expected. Check:
  1. x-astrolabe-category and x-astrolabe-complexity headers.
  2. active modes from /health.
  3. whether cost guardrails or premium-route blocks changed final route.
  4. whether ASTROLABE_FORCE_MODEL is set.

​
est_usd=n/a in logs

What it means: upstream usage token fields were not provided. Fix:
  • expected for some providers/responses; no action required unless cost reporting is mandatory

​
Config change had no effect

Check:
  1. Astrolabe was restarted after env changes.
  2. You edited the correct environment scope (local vs deployment).
  3. /health shows expected normalized values.
  4. Variable names and values match Configuration.

​
Last-resort debug snapshot

Capture these for debugging:
  1. request body (without secrets)
  2. response status + headers (x-astrolabe-*)
  3. /health output
  4. relevant server log line (category, route, chosen_model, final_model, selfcheck_score)