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

# Troubleshooting Common Issues in Agent Therapy API

> Diagnose and resolve common issues with Agent Therapy — authentication errors, session failures, unexpected health scores, and integration problems.

This guide covers the most common issues you may encounter when using Agent Therapy, along with step-by-step fixes. If you work through the relevant section and your problem is still unresolved, contact our support team at [support@agenttherapy.ai](mailto:support@agenttherapy.ai) with your session ID or request details and we'll investigate promptly.

***

## Authentication Errors

> **401 Unauthorized**
>
> Your API key is either missing from the request or invalid.
>
> **What to check:**
>
> 1. Confirm you're passing your key in the `Authorization` header using the `Bearer` scheme:
>    ```http theme={null}
>    Authorization: Bearer at_live_xxxxxxxxxxxxxxxxxxxx
>    ```
>
> 2. Verify the key is active in **Dashboard → Settings → API Keys**. A key that has been rotated or deleted will always return `401`.
>
> 3. Make sure there are no leading/trailing spaces in the key value — copy it directly from the dashboard.
>
> > [!WARNING]
> >
> > Never hardcode your API key in client-side code or commit it to version control. Use environment variables or a secrets manager.

> **403 Forbidden**
>
> Your API key is valid and recognized, but it doesn't have permission to perform the requested action.
>
> **What to check:**
>
> 1. **Plan limits** — some endpoints (e.g., bulk export, EU region access) are restricted to Pro or Enterprise plans. Check whether the feature you're calling is available on your current plan.
> 2. **Key scopes** — if you created a restricted key (e.g., read-only), it won't be able to create sessions or modify settings. Generate a new key with the correct scopes in **Settings → API Keys → Create Key**.
> 3. **Resource ownership** — you cannot access sessions or agents that belong to a different organization.

> **429 Too Many Requests**
>
> You've exceeded the API rate limit for your key. Limits are applied **per minute, per key**.
>
> **What to check:**
>
> 1. Inspect the response headers for limit details:
>    ```http theme={null}
>    X-RateLimit-Limit: 60
>    X-RateLimit-Remaining: 0
>    X-RateLimit-Reset: 1710000060
>    ```
> 2. Implement **exponential backoff** in your client — wait, then retry with increasing delays:
>    ```python theme={null}
>    import time, random
>
>    def submit_with_backoff(fn, max_retries=5):
>        for attempt in range(max_retries):
>            response = fn()
>            if response.status_code != 429:
>                return response
>            wait = (2 ** attempt) + random.uniform(0, 1)
>            time.sleep(wait)
>        raise Exception("Max retries exceeded")
>    ```
> 3. If you're consistently hitting limits, consider batching requests or upgrading your plan for a higher rate ceiling.

***

## Session Issues

> **Session stuck in 'processing'**
>
> Sessions typically complete within **10–30 seconds**. If a session has been in `processing` for more than **5 minutes**, something has likely gone wrong.
>
> **What to do:**
>
> 1. Poll the status endpoint to get the current state and check for an `error` field:
>    ```bash theme={null}
>    curl https://api.agenttherapy.ai/v1/sessions/{session_id} \
>      -H "Authorization: Bearer <your_key>"
>    ```
>    ```json theme={null}
>    {
>      "id": "sess_abc123",
>      "status": "processing",
>      "error": null
>    }
>    ```
> 2. If `error` is non-null, follow the guidance in the **Session returns `failed` status** section below.
> 3. If `error` is null and it's been more than 5 minutes, contact support with the session ID — this may indicate a processing node issue on our end.

> **Session returns 'failed' status**
>
> A `failed` status means Agent Therapy received your log but could not analyze it. The response body will contain details:
>
> ```json theme={null}
> {
>   "id": "sess_abc123",
>   "status": "failed",
>   "error": {
>     "code": "LOG_TOO_SHORT",
>     "message": "Submitted log contains fewer than 3 turns. A minimum of 3 turns is required for analysis."
>   }
> }
> ```
>
> **Common error codes and fixes:**
>
> | `error.code` | Cause | Fix |
> | - | - | - |
> | `MALFORMED_LOG` | Log JSON is invalid or missing required fields | Validate your log against the [log schema docs](https://vizmaxxing.com/api/sessions.md) |
> | `EMPTY_LOG` | Log was submitted with no messages | Ensure your export pipeline is capturing messages before submission |
> | `LOG_TOO_SHORT` | Fewer than 3 conversation turns | Submit a longer sample; 3 turns is the minimum for meaningful analysis |
>
> > [!NOTE]
> >
> > Review the log schema requirements in the [Sessions API reference](https://vizmaxxing.com/api/sessions.md) to validate your log format before submission. Catching format errors early avoids consuming a session credit.

> **Low confidence findings**
>
> If your session results show findings with `confidence: low`, the log you submitted may not contain enough signal for the models to produce high-confidence assessments.
>
> **Why this happens:**
>
> * Logs with fewer than \~10 turns produce lower confidence scores across most finding categories.
> * Sparse logs (long gaps between turns, very short messages) provide less behavioral data.
>
> **What to do:**
>
> * Submit a longer conversation sample — aim for at least **20–50 turns** for accurate analysis.
>
> * For agents with short individual conversations, batch multiple conversations together in a single log submission.
>
> > [!TIP]
> >
> > The **Conversation Coverage** panel in the session detail view shows how much of each behavioral dimension was observable given your log length.

> **Health score seems too low or too high**
>
> The Agent Health Score reflects **only the log you submitted**, not your agent's lifetime history or overall behavior.
>
> **Common reasons a score seems off:**
>
> * **Too low** — the submitted log may have captured an unusual or edge-case conversation batch. Try submitting a more representative sample from a typical operational period.
> * **Too high** — a short or narrow log might not expose the issues that occur in broader usage. Increase the sample size and diversity of conversations.
>
> If you believe a score is systematically miscalibrated for your agent type or use case, use the **Feedback** button on the session detail page to flag it — this directly informs model improvement.

***

## Integration Problems

> **LangChain callback not firing**
>
> If you're using the Agent Therapy LangChain handler and no sessions are being created, the callback is likely not attached at the right level.
>
> **Most common mistake — attaching to the LLM instead of the agent:**
>
> ```python theme={null}
> # ❌ Wrong — callback only fires for LLM calls, misses agent-level events
> llm = ChatOpenAI(callbacks=[AgentTherapyHandler()])
> agent = initialize_agent(tools, llm, ...)
>
> # ✅ Correct — callback fires for all agent events
> handler = AgentTherapyHandler(api_key="at_live_xxx")
> agent = initialize_agent(tools, llm, callbacks=[handler])
> ```
>
> **Also check:**
>
> * Enable `verbose=True` on the agent temporarily to confirm the callback chain is executing:
>   ```python theme={null}
>   agent = initialize_agent(tools, llm, callbacks=[handler], verbose=True)
>   ```
> * Ensure the handler is not catching and silently swallowing exceptions — set `raise_error=True` during debugging.

> **OpenAI thread export returns empty**
>
> If the exported thread contains no messages, check the following:
>
> 1. **Thread ID** — confirm the thread ID is correct. OpenAI thread IDs follow the format `thread_xxxxxxxxxxxxxxxxxx`. A typo will return an empty thread rather than an error.
> 2. **API key scopes** — your OpenAI key must have the `threads:read` scope (also listed as **"Thread messages: Read"** in the OpenAI platform permissions UI). Keys without this scope return an empty message list silently.
>    ```bash theme={null}
>    # Verify the thread exists and your key can read it
>    curl https://api.openai.com/v1/threads/{thread_id}/messages \
>      -H "Authorization: Bearer $OPENAI_API_KEY" \
>      -H "OpenAI-Beta: assistants=v2"
>    ```
> 3. **Thread age** — OpenAI automatically deletes threads after 60 days of inactivity. Threads older than this cannot be retrieved.

> **AutoGen messages missing timestamps**
>
> By default, AutoGen's message objects don't include timestamps, and some export configurations strip metadata. Agent Therapy will still process and score logs without timestamps — **no action is required**.
>
> However, be aware:
>
> * **Temporal analysis** (e.g., detecting response latency patterns or time-based drift) will be skipped when timestamps are absent.
> * Overall scoring accuracy may be **slightly reduced** compared to logs with full metadata.
>
> To add timestamps, wrap AutoGen message capture with your own metadata layer:
>
> ```python theme={null}
> from datetime import datetime, timezone
>
> def capture_message(sender, message, recipient):
>     return {
>         "role": sender.name,
>         "content": message,
>         "timestamp": datetime.now(timezone.utc).isoformat()
>     }
> ```

***

## Dashboard & UI Issues

> **Agent not appearing in dashboard**
>
> After registering a new agent via the API, it appears in the dashboard **immediately** — no waiting period is required.
>
> **If you don't see it:**
>
> 1. **Hard-refresh** the page (`Cmd+Shift+R` on macOS, `Ctrl+Shift+R` on Windows/Linux) to clear any cached state.
> 2. Confirm the registration request returned a `201 Created` response with an agent ID. A `200 OK` without an agent ID indicates the call may have hit a read endpoint instead.
> 3. Check that you're logged into the correct organization — agents are org-scoped and won't appear if you're viewing a different org's dashboard.

> **Alerts not firing**
>
> If you've configured alerts but aren't receiving notifications, work through the following:
>
> **For all alert channels:**
>
> * Go to **Settings → Alerts** and confirm the alert rule is enabled (toggle is green) and the threshold is set correctly.
> * Check the **Alert History** tab to see if the alert fired but the notification failed, or if it never triggered at all.
>
> **For Slack webhooks:**
>
> 1. Verify the webhook URL is correct — Slack webhook URLs follow the format `https://hooks.slack.com/services/T.../B.../...`.
> 2. Confirm the Slack app connected to the webhook still has **posting permissions** for the target channel. If the channel was made private after the webhook was created, permissions may have been revoked.
> 3. Test the webhook directly:
>    ```bash theme={null}
>    curl -X POST https://hooks.slack.com/services/YOUR/WEBHOOK/URL \
>      -H "Content-Type: application/json" \
>      -d '{"text": "Agent Therapy webhook test"}'
>    ```
>    A successful test returns `ok`. Any other response indicates a permissions or URL issue.
>
> **For PagerDuty and Datadog:**
>
> * Re-authenticate the integration in **Settings → Integrations** — access tokens can expire.
> * Confirm the integration key or API key used has write permissions on the target service.

***

## Getting More Help

> **[Contact Support](mailto:support@agenttherapy.ai)**
>
> Reach our support team directly. Include your session ID or request ID for the fastest resolution.

> **[API Status](https://status.agenttherapy.ai)**
>
> Check real-time API uptime, ongoing incidents, and historical availability on our status page.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.