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.	The cause varies; see below.
`404`	No such template or instance, or a Token Factory path that no model serves.	Confirm the identifier. A model name that isn’t in the catalog is a `400`, not a `404`.
`409`	A conflicting state, such as the previous instance still being deleted, or email verification being required first.	Follow the `code` in the body, or wait and retry.
`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" }

Token Factory errors come from two places, and the shapes differ.

Errors raised by the gateway, such as an invalid key, an unknown model or 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, such as a rejected credential, admission control or an unreachable gateway, 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.

Errors from a model service on your instance 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 produced, verbatim. A 403 from the proxy means the key doesn’t match the instance, or the instance isn’t running a model service. A 502 means vLLM isn’t accepting connections yet. Everything else is your server talking.

Common cases

400 Each user can only have one active instance: Destroy the current instance first. See DELETE /api/notebook/current.

400 Insufficient credits: Your balance doesn’t cover one hour on the chosen size. Redeem a coupon or choose a smaller size. Only the Global site checks this before launch. See Credits.

400 {"code": "catalog_image_not_found"}: The image isn’t in the catalog for your account, or has been retired. Pick one from the Image list on Home. On the China site, china_image_not_remote_ready means the image can’t be launched there yet; pick another one.

401 Login required: The endpoint takes a browser session, and an API key was sent instead. Use Radeon Cloud CLI to script instances.

403 resource_selection_not_assigned: The resource pool or size isn’t assigned to your account. Choose one listed under Size and Resource pool on Home.

403 {"code": "account_not_verified"}: The account is still under review. The body carries a redirect to the review page.

403 or 404 Instance not found on an instance URL: The instance belongs to someone else, has been destroyed, or the request has no browser session. An API key doesn’t work there. Open JupyterLab from Home while signed in. 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 is busy: Too many requests in flight platform-wide. Retry-After is short, 5 seconds by default.

Debugging checklist

Confirm you’re calling the right base URL. Token Factory and a model service on your instance use different hosts and paths, and a model service’s base URL can change when you relaunch. Copy it from the instance card again.

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

For a model service, 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 Token Factory model list has probably changed. Re-resolve with GET /v1/models.