> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qumo-deploy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Guide

> Diagnose and resolve common relay networking, authentication, and billing errors.

# Troubleshooting Guide

This guide helps you identify and resolve common issues encountered when integrating with the Qumo Deploy control plane and media relay network.

***

## 1. Relay & WebTransport Connectivity

### WebTransport / QUIC Connection Drops or Timeouts

**Symptom:** Client connection fails during initial handshake or times out when connecting to an assigned relay URL (e.g. `https://tyo1.relay.qumo.live:4433`).

**Causes & Solutions:**

* **UDP Port 4433 Blocking**: Media over QUIC (MoQ) and WebTransport run on top of HTTP/3 / UDP. Many corporate firewalls and VPNs block outbound UDP traffic on non-standard ports.
  * *Fix*: Ensure outbound UDP on port `4433` (and standard UDP `443`) is permitted on your network or security group.
* **Relay Liveness Degradation**: The control plane monitors node heartbeats. If a relay has missed its heartbeat interval, the credential response marks its status as `degraded`.
  * *Fix*: Always inspect the `fallback` array in your issued credential response (`cred.fallback`) and automatically retry connection against the secondary edge endpoints.

```typescript Fallback Pattern theme={null}
const cred = await client.credentials.issue({ scopes: ["relay:session"] });
const targetRelay = cred.relays?.[0]?.url || `https://${cred.fallback?.[0]}`;
```

***

## 2. Authentication & Authorization Errors

### `401 Unauthorized`

* **Expired Session Token**: Interactive browser sessions expire after 24 hours. The CLI or frontend will automatically clear invalid tokens on logout.
* **Malformed Secret Key**: API keys must follow the format `qumo_<env>_<64-hex>`. Plaintext keys are shown only once at creation.
* **Revoked Token (`jti`)**: If an active credential has been revoked via `POST /admin/v1/credentials/{jti}/revoke`, all edge relays immediately reject the token via in-memory revocation bloom filters.

### `403 Forbidden`

* **Scope vs. Permission Mismatch**: Even if an API key carries the wildcard `*` scope, the request will fail with `403` if the calling principal (User or Bot) does not hold the required IAM role binding (e.g. `roles/project.admin`).
* **IP Allowlist Enforcement**: If an IP allowlist rule exists on the bot or API key, requests originating from unauthorized CIDR ranges will be blocked with `403 Forbidden (ip not allowed)`.
* **Missing CSRF Token in Cookie Requests**: When invoking mutating routes (`POST`, `PUT`, `DELETE`) with a session cookie, the client must echo the `X-CSRF-Token` header.

***

## 3. Rate Limits & Billing Quotas (429 vs. 402)

It is critical to distinguish between transient rate limits and billing quota limits:

| Error Code              | Meaning                                                                                              | Action Required                                                                                                    |
| :---------------------- | :--------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- |
| `429 Too Many Requests` | **Transient Rate Limiting**. Triggered by rapid login attempts or frequent checkout creations.       | Implement exponential backoff with jitter and retry after the specified window (e.g. 1 minute).                    |
| `402 Payment Required`  | **Plan Entitlement Exceeded**. The tenant has reached its maximum concurrent relay connection limit. | Do **not** loop or retry. Upgrade the tenant subscription plan via the console (`/plans`) or revoke idle sessions. |

<Note>
  **Console Screenshot Placeholder:**

  > *Screenshot showing the 402 Plan Cap notification banner and the Upgrade CTA button in Stream Studio.*
</Note>

***

## 4. CLI Device Flow Timeouts

**Symptom:** `qumod login` outputs `Authorization timed out or expired. Please run 'qumod login' again.`

**Cause:** The RFC 8628 OAuth 2.0 Device Flow user verification code expires after 15 minutes if unapproved in the browser.

**Fix:**

1. Run `qumod login`.
2. Ensure you visit the verification URL (`https://console.qumo-deploy.com/device`) and enter the 8-character user code.
3. For automated environments, skip the interactive flow entirely by exporting `QUMO_TOKEN="sec_..."`.