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

# Common Issues

> Solutions to the most common problems.

## 401 when requesting a token

1. **Check credentials are loaded**
   ```python theme={null}
   import os
   print("Client ID:", os.environ.get("AGENT_CLIENT_ID", "NOT SET"))
   print("Secret set:", bool(os.environ.get("AGENT_CLIENT_SECRET")))
   ```

2. **Check agent status** — go to **Agents** and find your agent. Status must be **Active**. Suspended or Revoked agents can't authenticate.

3. **Verify the base URL** — make sure you're not pointing at `localhost` in production.

4. **Check if credentials were rotated** — if someone rotated credentials, the old secret is invalid. Rotate again from the agent's Settings tab.

***

## 403 — token request denied

1. **Check assigned policies** — go to **Agents → \[your agent] → Settings → Policies**. No policies = no access.

2. **Use the Policy Simulator** — go to **Policies → \[your policy] → Simulate** and test the exact request.

3. **Check scope format** — scopes are case-sensitive and colon-separated:
   ```
   ❌ "read"           ← too vague
   ❌ "Stripe:Read"    ← wrong case
   ✅ "stripe:customer:read"
   ```

4. **Check the policy is active** — verify **Active** is on and **Shadow Mode** is off.

***

## Token expired too quickly

The default is 10 minutes. Options:

**Set a custom TTL** — go to **Agents → \[your agent] → Settings → Token Lifetime**.

**Reuse the client** — make sure you're not creating a new `OculusClient` per request:

```python theme={null}
# ✅ Good — one client, tokens cached and renewed automatically
client = OculusClient(client_id="...", client_secret="...")

# ❌ Bad — new client every call, no caching
def my_function():
    client = OculusClient(...)  # don't do this
```

***

## Policy changes not taking effect

Policy decisions are cached for 60 seconds. Wait up to 60 seconds after saving. Also verify:

* The policy is **Active** (not Shadow Mode)
* The policy is **assigned** to the agent
* The Rego syntax is valid (use the **Preview** button)

***

## No audit logs visible

* **Check the date range** — the viewer defaults to the last 24 hours. Expand it.
* **Clear filters** — active filters may be hiding events.