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_AUTHHTTP 401

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

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

INVALID_KEYHTTP 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.

INVALID_TOKENHTTP 401

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

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

rate_limit_exceededHTTP 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://docs.rivenai.io/errors#rate_limit_exceeded"
  }
}

Two variants: (a) burst RPM/TPM exceeded — honor 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_exceededHTTP 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_EXHAUSTEDHTTP 503

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

Riven retries healthy backends before returning this. Treat as transient: retry with exponential backoff.

VALIDATION_ERRORHTTP 400

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

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

Retry guidance