Errors & Troubleshooting

EVERY ERROR CARRIES A REQUEST ID · USE IT

MiaRouter normalizes upstream chaos into one error shape. Relay errors arrive in OpenAI-style JSON with a request id appended to the message; console API errors arrive as {"success": false, "message": "…"}.

1The error shape

{
  "error": {
    "message": "user quota is not enough … (request id: 20261003153000-abcdef)",
    "type": "new_api_error",
    "code": "insufficient_user_quota"
  }
}

The request id in the message is the one thing support can trace end-to-end. Copy the whole message, not a paraphrase of it.

2Status codes

HTTP	Meaning on MiaRouter	First move
`400`	Malformed body, bad parameters.	Validate your JSON; check the endpoint's expected format.
`401`	Key missing, invalid, disabled, expired, or exhausted.	Check key state on the Keys page; test with the `/v1/models` curl.
`402`	Payment required — e.g. a dedicated pool's paid period lapsed.	Renew the pool.
`403`	Access denied: key used on the wrong domain (pool keys vs main keys), banned user, group not permitted.	Match the key to the domain it belongs to.
`404`	Model not found, or no pool at that subdomain.	Copy the model name from the pricing page exactly.
`429`	Rate limit: your key's RPM cap, the model's request limit, or login/verification throttles.	Back off exponentially; reduce concurrency.
`500`	Upstream provider failed after retries, or an internal error.	Retry once; if it persists, escalate with the request id.
`503`	Temporarily unavailable: pool still preparing, or system under load protection.	Wait and retry.

3The usual suspects, decoded

You see	It means	Fix
`user quota is not enough, user quota: $x, need quota: $y`	Account credits ran out mid-request.	Top up: Credits & Billing. Check Usage Logs for what burned it.
`token quota is not enough …`	That key's own quota is exhausted (not the account).	Raise/disable the key quota on the Keys page.
`no available channel exists for model X in group Y`	No upstream could serve that model right now — capacity, health checks, or group mapping.	Retry; try another model; if persistent, report with the request id.
`Invalid token` / 401 on every call	Key wrong, disabled, or typo'd.	The `/v1/models` curl from Agents isolates auth from everything else.
`this API key only works on its dedicated pool subdomain`	Pool key used on the main domain.	Use it on `yourpool.miarouter.online`, or use a normal key on the main domain.
`this API key does not belong to this dedicated pool`	Main-domain key used on a pool subdomain (or wrong pool).	Same answer, mirrored.
`this dedicated pool has expired, renew it to continue`	The pool's paid period ended; requests get 402.	Renew from the Dedicated Pools page.
`sensitive_words_detected`	The request tripped the platform's word filter.	Rephrase. Arguing rarely improves the filter.
Empty/partial stream then disconnect	Client disconnected (`client_gone`) or upstream stream ended early.	Check your client's timeouts; retry idempotently.

4Troubleshooting order

Auth: the /v1/models curl. 200 → auth fine. 401 → key problem, stop here.
Key state: Keys page — enabled, unexpired, unexhausted, quota above zero.
Balance: Dashboard — credits remaining, subscription windows not capped out.
Model: exact name from the pricing page, no creative spellings.
Logs: Usage Logs, filter by time — the request id tells you the model, group, channel outcome, and cost.
Escalate: Contact with the request id. "It does not work" is not a report; the request id is.