Errors

Errors are returned as JSON with a stable machine-readable code. HTTP status classes: 401 — authentication, 402 — quota, 429 — rate limiting, 400 — validation, 5xx — upstream availability.

`NO_AUTH` — HTTP 401#

payload

{"error": "Unauthorized", "code": "NO_AUTH"}

No Authorization header was sent. Add Authorization: Bearer rvn_....

`INVALID_KEY` — HTTP 401#

payload

{"error": "Invalid key", "code": "INVALID_KEY"}

The key is unknown, revoked, or rotated away. Mint or rotate a key in the console and retry — see Authentication & keys.

`INVALID_TOKEN` — HTTP 401#

payload

{"error": "Invalid token format", "code": "INVALID_TOKEN"}

The bearer token is neither an rvn_ key nor a valid signed-in session token.

`rate_limit_exceeded` — HTTP 429#

payload

{
  "error": {
    "code": "rate_limit_exceeded",
    "type": "plan_limit",
    "message": "Model riven-pro is not available on tier free. Upgrade required.",
    "retry_after_ms": 0,
    "docs": "https://rivenai.io/docs/errors#rate-limit-exceeded"
  }
}

Two variants: (a) burst RPM/TPM exceeded — honour retry_after_ms and back off; (b) type: "plan_limit" — the model is not included in your plan, so retrying will not help; upgrade the plan or pick an included model.

`quota_exceeded` — HTTP 402#

payload

{
  "error": {
    "code": "quota_exceeded",
    "message": "Your monthly quota has been used up. Refreshes on 2026-08-01.",
    "resetDate": "2026-08-01",
    "topupUrl": "https://chat.rivenai.io/settings/billing?tab=quota",
    "overageEnabled": false
  }
}

The billing-cycle allowance is spent. Wait for the reset date, enable overage, or top up via topupUrl. Check standing anytime with GET /billing/quota.

`UPSTREAMS_EXHAUSTED` — HTTP 503#

payload

{"error": "All inference upstreams unavailable", "code": "UPSTREAMS_EXHAUSTED", "tier": "cloud", "attempted": ["gateway"]}

Riven retries healthy backends before returning this — both on-prem replicas and cloud fallback. Treat as transient: retry with exponential backoff.

`VALIDATION_ERROR` — HTTP 400#

payload

{"error": "...", "code": "VALIDATION_ERROR"}

The request body is malformed (missing messages, bad parameter types). The message names the offending field.

Retry guidance#

401 / 402 / `plan_limit` 429 — do not retry unchanged; fix the key, plan, or quota first.
Burst 429 — retry after retry_after_ms.
5xx — retry with exponential backoff and jitter; Riven has already attempted internal failover.

Search docs

Errors