Errors

Status codes

Code	Meaning	What to do
`400`	The request was rejected. Invalid parameter, an instance already running, or too few credits.	Read `detail` and fix the request. Retrying won’t help.
`401`	Missing, malformed, or unrecognised credential.	Check the `Authorization` header. Rotate the key if it may have been revoked.
`403`	Authenticated, but not permitted.	See below — the cause varies.
`404`	No such template or instance, or a Model API path that isn’t served.	Confirm the identifier. A model name that isn’t in the catalog is a `400`, not a `404`.
`409`	A conflicting state, such as email verification being required first.	Follow the `code` in the body.
`429`	Rate limited.	Wait for `Retry-After`, then back off. See Rate limits.
`502`	The upstream model gateway or serving backend is unreachable.	Transient. Retry with backoff.
`503`	Capacity temporarily exhausted, or a feature is disabled.	Retry after the interval in `Retry-After`.

Error bodies

Platform API errors use FastAPI’s shape:

{ "detail": "Each user can only have one active instance" }

Public Free Model API errors come from two places, and the shapes differ.

Errors raised by the gateway — an invalid key, an unknown model, a gateway-side rate limit — use OpenAI’s shape, so existing OpenAI error handling works unchanged:

{
  "error": {
    "message": "Unauthorized: No API key provided.",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

On /v1/messages and /v1/messages/count_tokens the same errors use Anthropic’s envelope, so Anthropic SDKs parse them unchanged:

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Unauthorized: No API key provided."
  }
}

Errors raised by the platform in front of the gateway — credential rejection, admission control, gateway unreachable — are wrapped in detail like every other Platform API error:

{ "detail": "Invalid bearer token" }

{
  "detail": {
    "error": {
      "message": "Model API rate limit exceeded; please retry later",
      "type": "rate_limit_error",
      "code": "token_rate_limit_exceeded"
    }
  }
}

A model name that isn’t in the catalog is rejected by the gateway with 400 and Requested model <name> not supported; the request never reaches a backend. Errors the model itself raises, such as a prompt over the context limit, are passed through from the serving backend with its own status and message.

Dedicated Model API errors are none of the above. There is no gateway on that path, so once the proxy has admitted the request the body you get back is whatever vLLM or SGLang produced, verbatim. A 403 from the proxy means the key, the instance or the port didn’t match; a 503 means the instance is still starting. Everything else is your server talking.

Common cases

400 Each user can only have one active instance — destroy the current instance first. DELETE /api/notebook/current.

400 Insufficient credits — your balance is below the requested GPU count. Redeem a coupon or request fewer GPUs.

400 GPU count must be 1, 2, or 4 — no other values are allocatable.

400 Invalid image selected — the image isn’t in the catalog or has been disabled. List available images with GET /api/profile/templates.

403 {"code": "account_not_verified"} — the account is still under review. The body carries a redirect to the review page. Free model APIs stay available in the meantime.

403 You do not have access to this instance — the instance belongs to someone else, or you’re using a bearer key against the instance proxy, which requires a browser session. See Authentication.

502 Model gateway is unavailable — the gateway is down or unreachable. Retry with backoff; if it persists across several minutes, it’s an outage rather than something on your side.

503 Model gateway connection pool exhausted — too many requests in flight platform-wide. Retry-After is short, usually 5 seconds.

Debugging checklist

Confirm you’re calling the right base URL — the shared and dedicated endpoints are different hosts and paths, and a dedicated URL changes every time you relaunch.

Confirm the key is being sent, and sent as Authorization: Bearer rc-.... A missing header and an invalid key both produce 401.

For a dedicated endpoint, confirm the instance is ready and the model has finished loading. vLLM answers the port before weights are loaded, so early requests can fail with backend errors that look like platform problems.

If a call worked yesterday and fails today with 400 Requested model ... not supported, the shared catalog has probably changed. Re-resolve with GET /v1/models.