Troubleshooting

Start with the error code

Every error Janus itself returns has a stable code in the error body (and a request_id to quote). Find the code in the sections below; the error catalog has the full cause and fix for each. Errors that come from the provider are passed through unchanged and do not use these codes.

Streaming requests already returned HTTP 200 before anything could go wrong, so a failure mid-stream arrives as a final data: frame with an error object instead of an HTTP status. Check the last frame when a stream ends without [DONE].

I got a 401: my key is not accepted

policy.token_invalid — the token is missing, mistyped, revoked, or belongs to a deleted account. Check the API Tokens page: a revoked token shows as revoked. Confirm your client sends Authorization: Bearer <token> and not the token alone.

policy.service_token_expired — a service token reached the expiry set when it was created. An administrator issues a replacement under Administration → Service tokens.

authentication_error — a browser call to the web API had no valid session; it expired after 24 hours or 4 idle hours. Sign in again.

I got a 403: I am not allowed

policy.model_not_granted — the model is not enabled, or you hold no grant for it. Call GET /v1/models to see what you can use; ask an administrator for a grant.

policy.user_disabled — an administrator deactivated your account. Every call is refused until it is re-enabled.

policy.endpoint_blocked — a policy rule matched the request. The reason field gives the administrator’s explanation, or names the rule and the clause that fired.

policy.security_blocked — a Security Gateway check refused the request or withheld the response; error.param names the check (secrets, pii, terms, shape, prompt_injection, content_safety); Child Safety refusals carry no param. Remove the flagged material and retry, or give the request_id to an administrator. If the message says the policy fails closed, the classifier was unreachable and nothing matched.

policy.subscription_reauth_required — a my/… model uses your personal provider subscription and its sign-in stopped working. Reconnect it on the Subscriptions page.

policy.service_token_scope — a service token was used outside /v1. Service tokens only make model calls.

permission_error — your account lacks the role for an administrative action.

I got a 429: too many requests or quota used up

policy.quota_exceeded — a token, spend, or request quota is used up. Retrying before reset_at fails the same way; ask for a higher limit if you need one.

policy.rate_limit — a per-minute rate limit was exceeded. Wait retry_after seconds.

upstream.rate_limit — the provider throttled the gateway itself. You receive the provider’s own 429 body; the request log records it under this code. Back off and retry. Janus does not retry generative calls for you, because a retry is a second charge — except that a load-balanced managed model hands the request to its next model before anything is generated.

I got a 5xx: the model did not answer

upstream.unavailable (503) — the provider could not be reached or timed out. Retry shortly; an administrator can check the upstream under Administration → Settings → System status.

policy.managed_model_unavailable (503) — the managed model (alias) you called points at a missing or disabled model. Your request is fine; call another model until an administrator repairs the alias.

policy.managed_model_fallback_exhausted (503) — the alias target is down and its configured fallback cannot take over either. Retry later or report the request_id.

server_error (500) — an unexpected gateway fault. Retry once; if it recurs, quote the request_id to whoever runs the gateway.

My stream stopped early

Read the last frame. upstream.stream_interrupted means the provider dropped the connection or closed the stream without finishing; the text you received is incomplete, so retry. policy.response_too_large means the stream passed the gateway response cap (JANUS_MAX_RESPONSE_BYTES); ask for a shorter answer. A non-streaming answer larger than the cap is delivered in full, with its tokens estimated from its size. policy.security_blocked means a guardrail withheld the rest. policy.quota_exceeded means a hard-kill quota ran out mid-answer.

If there is no error frame at all, check your own client and proxies for read timeouts shorter than the answer takes.

I got a 400, 404, 409 or 413

invalid_request_error — the body was malformed or a required field such as model was missing (400); the body is too large for the provider adapter to rewrite (413); or an admin change conflicts with things that depend on it (409). The message and param field say what to fix.

not_found_error (404) — the path or the item does not exist, or is not visible to you. For model calls the base URL must end in /v1.

Administrators: I got a 402

license.required — creating something new needs a valid license; existing configuration keeps running. Install or renew the key under Administration → Settings → License & updates.

license.feature_not_licensed — the feature is not in the installed edition. Install a key that includes it, or leave it off.

license.seats_exhausted — every licensed seat is in use, so a new Janus account cannot be added or a disabled one turned back on. Free a seat by disabling an account, or add seats to the key.

Administrators: a change answered 500 audit.write_failed

audit.write_failed — the gateway runs the STIG profile, which saves an administrative change only together with its audit record. The audit record could not be written, so the change was not saved. Fix the database (disk space, permissions, connectivity) and try again.

My model is missing from /v1/models

Either the model is not enabled, or you hold no grant for it. Both are administrator actions. A model that has never been priced cannot be enabled at all — an administrator must save a rate card first ($0 rates are allowed for self-hosted models).

A model is slow

The Models page shows each model’s typical speed (tokens per second over the last 7 days) and how busy it is (jobs per day, with a trend arrow). Pick a faster model for interactive work. A long wait before the first word usually means a long prompt or a busy server rather than a slow model.

My dashboard shows zero

Metering is written just after the response is delivered, so allow a few seconds. Confirm the time range covers the request. If the call was refused before reaching a provider, it is still recorded, but with zero tokens and its error code set.

I am burning quota faster than expected

Open the request log and look at token_accounting_method. Requests marked “estimated from byte count” were priced from the generated text because the provider reported no usage block — most often on the catch-all route or on a stream the provider cut off. Cached input tokens are also counted in tokens_in.