Errors & support
When Chat, the API, or imux official models fail, you get a readable message, a stable error code, and a support ref (requestId). This page shows how to diagnose quickly and how to report issues.
Start with the Ref line at the end of the error (e.g. mbr_xxx · upstream_error · stage=upstream · HTTP 502). Paste that line when contacting support so we can correlate server logs.
Where errors appear
- imux 原生 App: Agent Chat bubble shows human copy + Ref; Console has [AgentChatProvider] logs.
- Web Chat / Playground（/playground · chat.clavue.com): red error banner + Ref; browser console logs [clavue-chat] membership error.
- API（
api.clavue.com/v1/*/www.clavue.com/api/membership/v1/*): JSON envelope + headers x-imux-request-id / x-imux-error-code / x-imux-error-stage.
How to read the support Ref
Typical format:
Official model upstream failed. Retry in a moment, or switch model (e.g. clavue-2.1-fast).
Slow down and retry later.
Ref: mbr_mrz… · upstream_error · stage=upstream · HTTP 502 · up=500| Part | Meaning |
|---|---|
mbr_… | requestId — correlates one request end-to-end |
upstream_error | stable error code — drives recovery |
stage=upstream | pipeline stage: auth / quota / upstream / validation… |
HTTP 502 | HTTP status returned to you (may be mapped, e.g. upstream 401→503) |
up=500 | raw upstream status when available |
30-second triage
- Confirm you are signed in (Account shows email / plan).
- Read the code: quota / rate limit → Account & Pricing; upstream_* → retry or switch model.
- Try another official model (auto ↔ clavue-2.1-fast).
- Still failing: copy the full error (including Ref) and report.
Common error codes
code | HTTP | Meaning | What you can do |
|---|---|---|---|
sign_in_required | 401 | Not signed in, or session/token expired | Open Account and sign in again; CLI: re-run device login |
rate_limited | 429 | Too many requests (IP or plan RPM) | Wait and retry; upgrade plan for higher RPM |
quota_exceeded | 402 | Daily / weekly / monthly or boost quota empty | Upgrade, buy boost packs, check-in, or wait for reset |
official_models_only | 400 | Non-official model id in the request | Use auto / clavue / clavue-2.1 / -fast / -pro / -rev |
upstream_error | 502 | Official model upstream failed (e.g. openai_error) | Retry; switch model (e.g. clavue-2.1-fast); if persistent, report with Ref |
upstream_rate_limited | 429 | Upstream provider is rate-limiting | Slow down and retry later |
upstream_not_configured | 503 | Service misconfigured (ops side) | Retry later; report with requestId if it lasts |
upstream_model_unavailable | 502 | Mapped upstream model not available | Switch product model; report if all models fail |
context_length_exceeded | 400 | Prompt / history too long for context | Start a new chat or shorten the request |
internal_error | 500 | Unexpected server error | Retry; report with requestId if it repeats |
Full developer envelope: Developers and repo docs/membership-api-errors.md。
Signed in but still failing? Not always auth
Older opaque tokens like openai_error looked like “not signed in”. Now:
- True auth failure → code=sign_in_required, stage=auth
- Official upstream down → code=upstream_*, stage=upstream (turn quota refunded)
- Out of quota → code=quota_exceeded, stage=quota
Quota & boost packs
- Usage: /account · /usage
- Upgrade: /pricing
- Boost: check-in / invite / rush on Account; auto-spend after free quota.
How to report a problem
Include the following so we can jump to the requestId in one step:
- Full error text (including the Ref line)
- Where: imux app / Web Chat / API / CLI
- Approx. time (with timezone) and model id
- Repro steps; whether switching model or a new chat helps
- API users: x-imux-request-id header + response JSON
Do not paste API keys, passwords, full session cookies, or private chat content. requestId + codes are enough.
Channels: GitHub Issues · in-app feedback when available · community board.
API self-check
# Expect 401 + requestId + code=sign_in_required when logged out
curl -si https://api.clavue.com/v1/chat/completions \
-H "content-type: application/json" \
-H "x-imux-request-id: mbr_cli_demo_001" \
-d '{"model":"auto","messages":[{"role":"user","content":"hi"}]}' \
| head -40
# Signed-in call (replace TOKEN)
curl -si https://api.clavue.com/v1/chat/completions \
-H "Authorization: Bearer $TOKEN" \
-H "content-type: application/json" \
-d '{"model":"auto","messages":[{"role":"user","content":"hi"}]}'