Troubleshooting
Separate the synchronous inference path from the asynchronous accounting path:
Client -> public ingress -> Lumoswitch Access Key -> model group -> provider
Lumoswitch usage records -> Lumoswitch worker -> usage records and ledgerRecommended workflow
- Record the HTTP status, Lumoswitch Runtime request ID, client-facing model name, and access-key prefix.
- Send
GET /v1/modelswith the same key to the independent inference Base URL. - Check that the configuration, deployment group, Virtual Key, and budget report ready.
- Test each candidate upstream directly from the Lumoswitch console.
- For billing differences, compare Lumoswitch usage records with the worker import window and quarantine state.
Symptoms
| Status / symptom | Likely cause | Next step |
|---|---|---|
| 400 | Invalid request or unsupported parameter for the selected format | Retry a minimal request on an enabled public route |
| 401 | Missing, invalid, blocked, or deleted Virtual Key | Confirm the latest Lumoswitch Access Key |
| 403 | Model scope or provider permission | Check the key model allowlist and provider account |
| 404 / model not found | Wrong Base URL, route, or client-facing model name | Copy the inference URL and model name from the configuration |
| 422 | Budget exhausted (budget_exceeded) or an unprocessable request | For budget errors, check the allowance and reset period; otherwise, check request parameters |
| 429 | Lumoswitch Runtime rate/concurrency limit or provider throttling | Check the runtime limit first, then the provider quota |
| 5xx | No usable deployment or provider failure | Check candidate readiness and upstream connectivity |
| Usage delayed | Worker overlap window or temporary Spend API failure | Check worker health; imports are idempotent and retryable |
URL and route checks
- The OpenAI-compatible Base URL ends in
/v1; do not append it twice. - Public ingress allows only the unified OpenAI, Anthropic Messages, and Gemini generateContent routes documented in Protocols and compatibility.
- Lumoswitch control API is not an inference fallback and must not be configured as the client Base URL.
Share only the time range, status, request ID, key prefix, client-facing model name, and a redacted configuration summary. Never share complete access/provider keys, passwords, prompts, or personal data.
Lumoswitch risk controls
Review Lumoswitch runtime controls and billing incidents, including unpriced usage and settlement failures. Inspect evidence, restrictions, and resolution steps.
Desktop client guide
Download the Lumoswitch desktop client, select a model connection and coding Agent, preview the proposed setup, confirm it, and verify the resulting connection.